Proj PDF

PROJ coordinate transformation
software library
Release 5.1.0
PROJ contributors
Jun 01, 2018

CONTENTS
1 About 1
1.1 Citation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Download 3
2.1 Current Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 Past Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3 Installation 5
3.1 Installation from package management systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.1 Cross platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.2 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.3 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1.4 Mac OS X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2 Compilation and installation from source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.1 Autotools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.2 CMake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4 Using PROJ 9
4.1 Quick start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.2 Cartographic projection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.2.1 Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.2.2 False Easting/Northing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2.3 Longitude Wrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2.4 Prime Meridian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2.5 Axis orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.3 Geodetic transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.3.1 Transformation pipelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3.2 cs2cs paradigm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.3.3 Grid Based Datum Adjustments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.4 Environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.5 Known differences between versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.5.1 Version 5.0.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5 Applications 19
5.1 proj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.1.1 Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.1.2 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.1.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2 cct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
i
5.2.1 Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2.2 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.2.4 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.3 cs2cs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.3.1 Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.3.2 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.3.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.4 geod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.4.1 Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.4.2 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.4.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.4.4 Further reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.5 gie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.5.1 Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.5.2 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.5.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.5.4 gie command language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.5.5 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6 Coordinate operations 33
6.1 Projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.1.1 Albers Equal Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.1.2 Azimuthal Equidistant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.1.3 Airy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.1.4 Aitoff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.1.5 Modified Stererographics of Alaska . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.1.6 Apian Globular I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.1.7 August Epicycloidal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
6.1.8 Bacon Globular . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
6.1.9 Bipolar conic of western hemisphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
6.1.10 Boggs Eumorphic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
6.1.11 Bonne (Werner lat_1=90) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.1.12 Cal Coop Ocean Fish Invest Lines/Stations . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.1.13 Cassini (Cassini-Soldner) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
6.1.14 Central Cylindrical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
6.1.15 Central Conic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
6.1.16 Equal Area Cylindrical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
6.1.17 Chamberlin Trimetric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
6.1.18 Collignon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.1.19 Craster Parabolic (Putnins P4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.1.20 Denoyer Semi-Elliptical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.1.21 Eckert I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.1.22 Eckert II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
6.1.23 Eckert III . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
6.1.24 Eckert IV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
6.1.25 Eckert V . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
6.1.26 Eckert VI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.1.27 Equidistant Cylindrical (Plate Carrée) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.1.28 Equidistant Conic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.1.29 Euler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.1.30 Extended Transverse Mercator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
6.1.31 Fahey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
6.1.32 Foucaut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
ii
6.1.33 Foucaut Sinusoidal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
6.1.34 Gall (Gall Stereographic) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.1.35 Geostationary Satellite View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.1.36 Ginsburg VIII (TsNIIGAiK) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.1.37 General Sinusoidal Series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
6.1.38 Gnomonic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
6.1.39 Goode Homolosine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.1.40 Mod. Stererographics of 48 U.S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.1.41 Mod. Stererographics of 50 U.S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.1.42 Hammer & Eckert-Greifendorff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.1.43 Hatano Asymmetrical Equal Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.1.44 HEALPix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
6.1.45 rHEALPix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
6.1.46 Interrupted Goode Homolosine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
6.1.47 International Map of the World Polyconic . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
6.1.48 Icosahedral Snyder Equal Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
6.1.49 Kavraisky V . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
6.1.50 Kavraisky VII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
6.1.51 Krovak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
6.1.52 Laborde . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
6.1.53 Lambert Azimuthal Equal Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
6.1.54 Lagrange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
6.1.55 Larrivee . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
6.1.56 Laskowski . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
6.1.57 Lambert Conformal Conic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
6.1.58 Lambert Conformal Conic Alternative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
6.1.59 Lambert Equal Area Conic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
6.1.60 Lee Oblated Stereographic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
6.1.61 Loximuthal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
6.1.62 Space oblique for LANDSAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
6.1.63 McBryde-Thomas Flat-Polar Sine (No. 1) . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
6.1.64 McBryde-Thomas Flat-Pole Sine (No. 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
6.1.65 McBride-Thomas Flat-Polar Parabolic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
6.1.66 McBryde-Thomas Flat-Polar Quartic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
6.1.67 McBryde-Thomas Flat-Polar Sinusoidal . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
6.1.68 Mercator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
6.1.69 Miller Oblated Stereographic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
6.1.70 Miller Cylindrical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
6.1.71 Mollweide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
6.1.72 Murdoch I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
6.1.73 Murdoch II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
6.1.74 Murdoch III . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.1.75 Natural Earth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.1.76 Nell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
6.1.77 Nell-Hammer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
6.1.78 Nicolosi Globular . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
6.1.79 Near-sided perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
6.1.80 New Zealand Map Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
6.1.81 General Oblique Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
6.1.82 Oblique Cylindrical Equal Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
6.1.83 Oblated Equal Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
6.1.84 Oblique Mercator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
6.1.85 Ortelius Oval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
6.1.86 Orthographic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
iii
6.1.87 Perspective Conic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
6.1.88 Polyconic (American) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
6.1.89 Putnins P1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
6.1.90 Putnins P2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
6.1.91 Putnins P3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
6.1.92 Putnins P3’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
6.1.93 Putnins P4’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
6.1.94 Putnins P5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
6.1.95 Putnins P5’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
6.1.96 Putnins P6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
6.1.97 Putnins P6’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
6.1.98 Quartic Authalic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
6.1.99 Quadrilateralized Spherical Cube . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
6.1.100 Robinson . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
6.1.101 Roussilhe Stereographic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
6.1.102 Rectangular Polyconic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
6.1.103 Sinusoidal (Sanson-Flamsteed) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
6.1.104 Swiss. Obl. Mercator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
6.1.105 Stereographic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
6.1.106 Oblique Stereographic Alternative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
6.1.107 Gauss-Schreiber Transverse Mercator (aka Gauss-Laborde Reunion) . . . . . . . . . . . . . 114
6.1.108 Transverse Central Cylindrical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
6.1.109 Transverse Cylindrical Equal Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
6.1.110 Tissot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
6.1.111 Transverse Mercator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
6.1.112 Two Point Equidistant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
6.1.113 Tilted perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
6.1.114 Universal Polar Stereographic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
6.1.115 Urmaev V . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
6.1.116 Urmaev Flat-Polar Sinusoidal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
6.1.117 Universal Transverse Mercator (UTM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
6.1.118 van der Grinten (I) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
6.1.119 van der Grinten II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
6.1.120 van der Grinten III . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
6.1.121 van der Grinten IV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
6.1.122 Vitkovsky I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
6.1.123 Wagner I (Kavraisky VI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
6.1.124 Wagner II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
6.1.125 Wagner III . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
6.1.126 Wagner IV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
6.1.127 Wagner V . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
6.1.128 Wagner VI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
6.1.129 Wagner VII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
6.1.130 Web Mercator / Pseudo Mercator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
6.1.131 Werenskiold I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
6.1.132 Winkel I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
6.1.133 Winkel II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
6.1.134 Winkel Tripel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
6.2 Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
6.2.1 Axis swap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
6.2.2 Cartesian to geodetic conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
6.2.3 Lat/long (Geodetic alias) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
6.2.4 Unit conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
6.3 Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
iv
6.3.1 Kinematic datum shifting utilizing a deformation model . . . . . . . . . . . . . . . . . . . . 137
6.3.2 Helmert transform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
6.3.3 Molodensky transform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6.3.4 Horizontal grid shift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.3.5 Vertical grid shift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
6.4 The pipeline operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
6.4.1 Rules for pipelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
6.4.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
7 Resource files 151

7.1 External resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
7.2 Transformation grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
7.2.1 Free grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
7.2.2 Non-Free Grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
7.2.3 HARN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
7.2.4 HTDP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
7.3 Init files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
7.4 The defaults file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
8 Geodesic calculations 159

8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
8.2 Solution of geodesic problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
8.3 Additional properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
8.4 Multiple shortest geodesics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
8.5 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
9 Development 163
9.1 Quick start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
9.2 Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
9.3 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
9.4 Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
9.4.1 Key Thread Safety Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
9.4.2 projCtx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
9.4.3 src/multistresstest.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
9.5 Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
9.5.1 Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
9.5.2 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
9.5.3 Deprecated API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
9.6 Using PROJ in CMake projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
9.7 Language bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
9.7.1 Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
9.7.2 Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
9.7.3 TCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
9.7.4 MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
9.7.5 Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
9.7.6 Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
9.8 Version 4 to 5 API Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
9.8.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
9.8.2 Code example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
9.8.3 Function mapping from old to new API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
10 Community 193
10.1 Communication channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
10.1.1 Mailing list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
10.1.2 GitHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
v
10.2 Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
10.2.1 Help a fellow PROJ user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
10.2.2 Adding bug reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
10.2.3 Feature requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
10.2.4 Write documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
10.2.5 Code contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
10.2.6 Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
10.2.7 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
10.3 Guidelines for PROJ code contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
10.3.1 Code contributions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
10.3.2 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
11 FAQ 199
11.1 Where can I find the list of projections and their arguments? . . . . . . . . . . . . . . . . . . . . . . 199
11.2 How do I build/configure PROJ to support datum shifting? . . . . . . . . . . . . . . . . . . . . . . . 199
11.3 How do I debug problems with NAD27/NAD83 datum shifting? . . . . . . . . . . . . . . . . . . . . 200
11.4 How do I use EPSG coordinate system codes with PROJ? . . . . . . . . . . . . . . . . . . . . . . . 200
11.5 How do I use 3 parameter and 7 parameter datum shifting . . . . . . . . . . . . . . . . . . . . . . . 201
11.6 Does PROJ work in different international numeric locales? . . . . . . . . . . . . . . . . . . . . . . 201
11.7 Changing Ellipsoid / Why can’t I convert from WGS84 to Google Earth / Virtual Globe Mercator? . . 201
11.8 Why do I get different results with 4.5.0 and 4.6.0? . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
11.9 How do I calculate distances/directions on the surface of the earth? . . . . . . . . . . . . . . . . . . 202
11.10 What is the HEALPix projection and how can I use it? . . . . . . . . . . . . . . . . . . . . . . . . . 202
11.11 What is the rHEALPix projection and how can I use it? . . . . . . . . . . . . . . . . . . . . . . . . . 203
11.12 What options does PROJ allow for the shape of the Earth (geodesy)? . . . . . . . . . . . . . . . . . 203
11.13 What if I want a spherical Earth? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
11.14 How do I change the radius of the Earth? How do I use PROJ for work on Mars? . . . . . . . . . . . 204
11.15 How do I do False Eastings and False Northings? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
12 Glossary 205
Bibliography 207
Index 209
vi
CHAPTER
ONE
ABOUT
PROJ is a generic coordinate transformation software, that transforms geospatial coordinates from one coordinate
reference system (CRS) to another. This includes cartographic projections as well as geodetic transformations.
PROJ includes command line applications for easy conversion of coordinates from text files or directly from user
input. In addition to the command line utilities PROJ also exposes an application programming interface, or API in
short. The API let developers use the functionality of PROJ in their own software without having to implement similar
functionality themselves.
PROJ started purely as a cartography application letting users convert geodetic coordinates into projected coordinates
using a number of different cartographic projections. Over the years, as the need has become apparent, support for
datum shifts has slowly worked it’s way into PROJ as well. Today PROJ support more than a hundred different map
projections and can transform coordinates between datums using all but the most obscure geodetic techniques.
1.1 Citation
To cite PROJ in publications use:

PROJ contributors (2018). PROJ coordinate transformation software library. Open Source Geospatial
Foundation. URL http://proj4.org/.
A BibTeX entry for LaTeX users is
@Manual{,
title = {{PROJ} coordinate transformation software library},
author = {{PROJ contributors}},
organization = {Open Source Geospatial Foundation},
year = {2018},
url = {http://proj4.org/},
}
1.2 License
PROJ uses the MIT license. The software was initially released by the USGS in the public domain. When Frank
Warmerdam took over the development of PROJ it was moved under the MIT license. The license is as follows:
Copyright (c) 2000, Frank Warmerdam
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associ-
ated documentation files (the “Software”), to deal in the Software without restriction, including without
limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
1
PROJ coordinate transformation software library, Release 5.1.0
Software, and to permit persons to whom the Software is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions
of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARIS-
ING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
2 Chapter 1. About
CHAPTER
TWO
DOWNLOAD
Here you can download current and previous releases of PROJ. We only supply a distribution of the source code and
various resource files archives. See Installation for information on how to get pre-built packages of PROJ.
2.1 Current Release
• 2018-06-01 proj-5.1.0.tar.gz (md5)

• 2018-03-01 proj-datumgrid-1.7.zip
• 2018-03-01 proj-datumgrid-europe-1.0.zip
• 2018-03-01 proj-datumgrid-north-america-1.0.zip
• 2018-03-01 proj-datumgrid-oceania-1.0.zip
• PDF Manual proj.pdf
2.2 Past Releases
• 2018-04-01 proj-5.0.1.tar.gz (md5)

• 2018-03-01 proj-5.0.0.tar.gz
• 2016-09-02 proj-4.9.3.tar.gz
• 2015-09-13 proj-4.9.2.tar.gz
• 2015-03-04 proj-4.9.1.tar.gz
• 2016-09-11 proj-datumgrid-1.6.zip
3
4 Chapter 2. Download
CHAPTER
THREE
INSTALLATION
These pages describe how to install PROJ on your computer without compiling it yourself. Below are guides for
installing on Windows, Linux and Mac OS X. This is a good place to get started if this is your first time using PROJ.
More advanced users may want to compile the software themselves.
3.1 Installation from package management systems
3.1.1 Cross platform
PROJ is also available via cross platform package managers.
Conda
The conda package manager includes several PROJ packages. We recommend installing from the conda-forge
channel:
conda install -c conda-forge proj4
Docker
A Docker image with just PROJ binaries and a full compliment of grid shift files is available on DockerHub. Get the
package with:
docker pull osgeo/proj.4
3.1.2 Windows
The simplest way to install PROJ on Windows is to use the OSGeo4W software distribution. OSGeo4W provides
easy access to many popular open source geospatial software packages. After installation you can use PROJ from the
OSGeo4W shell. To install PROJ do the following:
Note: If you have already installed software via OSGeo4W on your computer it is likely that PROJ is already installed.
1. Download either the 32 bit or 64 bit installer.

2. Run the OSGeo4W setup program.
5
3. Select “Advanced Install” and press Next.

4. Select “Install from Internet” and press Next.
5. Select a installation directory. The default suggestion is fine in most cases. Press Next.
6. Select “Local packacke directory”. The suggestions is fine in most cases. Press Next.
7. Select “Direct connection” and press Next.
8. Choose the download.osgeo.org and press Next.
9. Find “proj” under “Commandline_Utilities” and click the package in the “New” column until the version you
want to install appears.
10. Press next to install PROJ.
You should now have a “OSGeo” menu in your start menu. Within that menu you can find the “OSGeo4W Shell”
where you have access to all the OSGeo4W applications, including proj.
For those who are more inclined to the command line, steps 2–10 above can be accomplished by executing the follow-
ing command:
C:\temp\osgeo4w-setup-x86-64.exe -q -k -r -A -s http://download.osgeo.org/osgeo4w/ -a
˓→x86_64 -P proj
3.1.3 Linux
How to install PROJ on Linux depends on which distribution you are using. Below is a few examples for some of the
more common Linux distributions:
Debian
On Debian and similar systems (e.g. Ubuntu) the APT package manager is used:
sudo apt-get install proj-bin
Red Hat
On Red Hat based system packages are installed with yum:
sudo yum install proj
3.1.4 Mac OS X
On OS X PROJ can be installed via the Homebrew package manager:
brew install proj
PROJ is also available from the MacPorts system:
sudo ports install proj
6 Chapter 3. Installation
3.2 Compilation and installation from source code
The classical way of installing PROJ is via the source code distribution. The most recent version is available from the
download page. You will need that and at least the standard proj-datumgrid package for a successful installation. The
following guides show how to compile and install the software using the Autotools and CMake build systems.
3.2.1 Autotools
FSF’s configuration procedure is used to ease installation of the PROJ system.
Note: The Autotools build system is only available on UNIX-like systems. Follow the CMake installation guide if
you are not using a UNIX-like operating system.
The default destination path prefix for installed files is /usr/local. Results from the installation script will be
placed into subdirectories bin, include, lib, man/man1 and man/man3. If this default path prefix is proper,
then execute:
./configure
If another path prefix is required, then execute:
./configure --prefix=/my/path
In either case, the directory of the prefix path must exist and be writable by the installer.
Before proceeding with the installation we need to add the datum grids. Unzip the contents of the proj-datumgrid
package into nad/:
unzip proj-datumgrid-1.7.zip -d proj-5.0.1/nad/
The installation will automatically move the grid files to the correct location. Alternatively the grids can be installed
manually in the directory pointed to by the PROJ_LIB environment variable. The default location is /usr/local/
share/proj.
With the grid files in place we can now build and install PROJ:
make
make install
The install target will create, if necessary, all required sub-directories.

Tests are run with:
make check
The test suite requires that the proj-datumgrid package is installed in PROJ_LIB.
3.2.2 CMake
With the CMake build system you can compile and install PROJ on more or less any platform. After unpacking the
source distribution archive step into the source- tree:
cd proj-5.0.1
3.2. Compilation and installation from source code 7

Create a build directory and step into it:
mkdir build
cd build
From the build directory you can now configure CMake and build the binaries:
cmake ..
cmake --build .
On Windows, one may need to specify generator:
cmake -G "Visual Studio 15 2017" ..
Tests are run with:
ctest
The test suite requires that the proj-datumgrid package is installed in PROJ_LIB.
8 Chapter 3. Installation
CHAPTER
FOUR
USING PROJ
The main purpose of PROJ is to transform coordinates from one coordinate reference system to another. This can be
achieved either with the included command line applications or the C API that is a part of the software package.
4.1 Quick start
Coordinate transformations are defined by, what in PROJ terminology is known as, “proj-strings”. A proj-string
describes any transformation regardless of how simple or complicated it might be. The simplest case is projection of
geodetic coordinates. This section focuses on the simpler cases and introduces the basic anatomy of the proj-string.
The complex cases are discussed in Geodetic transformation.
A proj-strings holds the parameters of a given coordinate transformation, e.g.
+proj=merc +lat_ts=56.5 +ellps=GRS80
I.e. a proj-string consists of a projection specifier, +proj, a number of parameters that applies to the projection and,
if needed, a description of a datum shift. In the example above geodetic coordinates are transformed to projected
space with the Mercator projection with the latitude of true scale at 56.5 degrees north on the GRS80 ellipsoid. Every
projection in PROJ is identified by a shorthand such as merc in the above example.
By using the above projection definition as parameters for the command line utility proj we can convert the geodetic
coordinates to projected space:
$ proj +proj=merc +lat_ts=56.5 +ellps=GRS80
If called as above proj will be in interactive mode, letting you type the input data manually and getting a response
presented on screen. proj works as any UNIX filter though, which means that you can also pipe data to the utility,
for instance by using the echo command:
$ echo 55.2 12.2 | proj +proj=merc +lat_ts=56.5 +ellps=GRS80

3399483.80 752085.60
PROJ also comes bundled with the cs2cs utility which is used to transform from one coordinate reference system to
another. Say we want to convert the above Mercator coordinates to UTM, we can do that with cs2cs:
$ echo 3399483.80 752085.60 | cs2cs +proj=merc +lat_ts=56.5 +ellps=GRS80 +to

˓→+proj=utm +zone=32
6103992.36 1924052.47 0.00
Notice the +to parameter that separates the source and destination projection definitions.
If you happen to know the EPSG identifiers for the two coordinates reference systems you are transforming between
you can use those with cs2cs:
9
$ echo 56 12 | cs2cs +init=epsg:4326 +to +init=epsg:25832

231950.54 1920310.71 0.00
In the above example we transform geodetic coordinates in the WGS84 reference frame to UTM zone 32N coordinates
in the ETRS89 reference frame. UTM coordinates
4.2 Cartographic projection
The foundation of PROJ is the large number of projections available in the library. This section is devoted to the
generic parameters that can be used on any projection in the PROJ library.
Below is a list of PROJ parameters which can be applied to most coordinate system definitions. This table does
not attempt to describe the parameters particular to particular projection types. These can be found on the pages
documenting the individual projections.
Parameter Description
+a Semimajor radius of the ellipsoid axis
+axis Axis orientation
+b Semiminor radius of the ellipsoid axis
+ellps Ellipsoid name (see proj -le)
+k Scaling factor (deprecated)
+k_0 Scaling factor
+lat_0 Latitude of origin
+lon_0 Central meridian
+lon_wrap Center longitude to use for wrapping (see below)
+no_defs Don’t use the /usr/share/proj/proj_def.dat defaults file
+over Allow longitude output outside -180 to 180 range, disables wrapping (see below)
+pm Alternate prime meridian (typically a city name, see below)
+proj Projection name (see proj -l)
+units meters, US survey feet, etc.
+vunits vertical units.
+x_0 False easting
+y_0 False northing
In the sections below most of the parameters are explained in details.
4.2.1 Units
Horizontal units can be specified using the +units keyword with a symbolic name for a unit (ie. us-ft). Alterna-
tively the translation to meters can be specified with the +to_meter keyword (ie. 0.304800609601219 for US feet).
The -lu argument to cs2cs or proj can be used to list symbolic unit names. The default unit for projected coordi-
nates is the meter. A few special projections deviate from this behaviour, most notably the latlong pseudo-projection
that returns degrees.
Vertical (Z) units can be specified using the +vunits keyword with a symbolic name for a unit (ie. us-ft). Alter-
natively the translation to meters can be specified with the +vto_meter keyword (ie. 0.304800609601219 for US
feet). The -lu argument to cs2cs or proj can be used to list symbolic unit names. If no vertical units are specified,
the vertical units will default to be the same as the horizontal coordinates.
Note: proj do not handle vertical units at all and hence the +vto_meter argument will be ignored.
10 Chapter 4. Using PROJ

Scaling of output units can be done by applying the +k_0 argument. The returned coordinates are scaled by the value
assigned with the +k_0 parameter.
4.2.2 False Easting/Northing
Virtually all coordinate systems allow for the presence of a false easting (+x_0) and northing (+y_0). Note that these
values are always expressed in meters even if the coordinate system is some other units. Some coordinate systems
(such as UTM) have implicit false easting and northing values.
4.2.3 Longitude Wrapping
By default PROJ wraps output longitudes in the range -180 to 180. The +over switch can be used to disable the
default wrapping which is done at a low level in pj_inv(). This is particularly useful with projections like the
equidistant cylindrical where it would be desirable for X values past -20000000 (roughly) to continue past -180
instead of wrapping to +180.
The +lon_wrap option can be used to provide an alternative means of doing longitude wrapping within
pj_transform(). The argument to this option is a center longitude. So +lon_wrap=180 means wrap lon-
gitudes in the range 0 to 360. Note that +over does not disable +lon_wrap.
4.2.4 Prime Meridian
A prime meridian may be declared indicating the offset between the prime meridian of the declared coordinate system
and that of greenwich. A prime meridian is declared using the “pm” parameter, and may be assigned a symbolic name,
or the longitude of the alternative prime meridian relative to greenwich.
Currently prime meridian declarations are only utilized by the pj_transform() API call, not the pj_inv() and
pj_fwd() calls. Consequently the user utility cs2cs does honour prime meridians but the proj user utility ignores
them.
The following predeclared prime meridian names are supported. These can be listed using with cs2cs -lm.
Meridian Longitude
greenwich 0dE
lisbon 9d07‘54.862”W
paris 2d20‘14.025”E
bogota 74d04‘51.3”E
madrid 3d41‘16.48”W
rome 12d27‘8.4”E
bern 7d26‘22.5”E
jakarta 106d48‘27.79”E
ferro 17d40’W
brussels 4d22‘4.71”E
stockholm 18d3‘29.8”E
athens 23d42‘58.815”E
oslo 10d43‘22.5”E
Example of use. The location long=0, lat=0 in the greenwich based lat/long coordinates is translated to lat/long
coordinates with Madrid as the prime meridian.
4.2. Cartographic projection 11

cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid

0 0
3d41'16.48"E 0dN 0.000
4.2.5 Axis orientation
Starting in PROJ 4.8.0, the +axis argument can be used to control the axis orientation of the coordinate system. The
default orientation is “easting, northing, up” but directions can be flipped, or axes flipped using combinations of the
axes in the +axis switch. The values are:
• “e” - Easting
• “w” - Westing
• “n” - Northing
• “s” - Southing
• “u” - Up
• “d” - Down
They can be combined in +axis in forms like:
• +axis=enu - the default easting, northing, elevation.
• +axis=neu - northing, easting, up - useful for “lat/long” geographic coordinates, or south orientated transverse
mercator.
• +axis=wnu - westing, northing, up - some planetary coordinate systems have “west positive” coordinate
systems
Note: The +axis argument does not work with the proj command line utility.
4.3 Geodetic transformation
PROJ can do everything from the most simple projection to very complex transformations across many reference
frames. While originally developed as a tool for cartographic projections, PROJ has over time evolved into a powerful
generic coordinate transformation engine that makes it possible to do both large scale cartographic projections as well
as coordinate transformation at a geodetic high precision level. This chapter delves into the details of how geodetic
transformations of varying complexity can be performed.
In PROJ, two frameworks for geodetic transformations exists, the cs2cs framework and the transformation pipelines
framework. The first is the original, and limited, framework for doing geodetic transforms in PROJ The latter is a
newer addition that aims to be a more complete transformation framework. Both are described in the sections below.
Large portions of the text are based on [EversKnudsen2017].
Before describing the details of the two frameworks, let us first remark that most cases of geodetic transformations can
be expressed as a series of elementary operations, the output of one operation being the input of the next. E.g. when
going from UTM zone 32, datum ED50, to UTM zone 32, datum ETRS89, one must, in the simplest case, go through
5 steps:
1. Back-project the UTM coordinates to geographic coordinates
2. Convert the geographic coordinates to 3D cartesian geocentric coordinates
3. Apply a Helmert transformation from ED50 to ETRS89

4. Convert back from cartesian to geographic coordinates

5. Finally project the geographic coordinates to UTM zone 32 planar coordinates.
4.3.1 Transformation pipelines
The homology between the above steps and a Unix shell style pipeline is evident. It is there the main architectural
inspiration behind the transformation pipeline framework. The pipeline framework is realized by utilizing a special
“projection”, that takes as its user supplied arguments, a series of elementary operations, which it strings together in
order to implement the full transformation needed. Additionally, a number of elementary geodetic operations, includ-
ing Helmert transformations, general high order polynomial shifts and the Molodensky transformation are available
as part of the pipeline framework. In anticipation of upcoming support for full time-varying transformations, we also
introduce a 4D spatiotemporal data type, and a programming interface (API) for handling this.
The Molodensky transformation converts directly from geodetic coordinates in one datum, to geodetic coordinates in
another datum, while the (typically more accurate) Helmert transformation converts from 3D cartesian to 3D cartesian
coordinates. So when using the Helmert transformation one typically needs to do an initial conversion from geodetic
to cartesian coordinates, and a final conversion the other way round, to arrive at the desired result. Fortunately, this
three-step compound transformation has the attractive characteristic that each step depends only on the output of the
immediately preceding step. Hence, we can build a geodetic-to-geodetic Helmert transformation by tying together
the outputs and inputs of 3 steps (geodetic-to-cartesian → Helmert → cartesian-to-geodetic), pipeline style. The
pipeline driver, makes this kind of chained transformations possible. The implementation is compact, consisting
of just one pseudo-projection, called pipeline, which takes as its arguments strings of elementary projections
(note: “projection” is the, slightly misleading, PROJ term used for any kind of transformation). The pipeline pseudo
projection is supplemented by a number of elementary transformations, all in all providing a framework for building
high accuracy solutions for a wide spectrum of geodetic tasks.
As a first example, let us take a look at the iconic geodetic → Cartesian → Helmert → geodetic case (steps 2 to 4 in
the example in the introduction). In PROJ it can be implemented as
proj=pipeline
step proj=cart ellps=intl
step proj=helmert
x=-81.0703 y=-89.3603 z=-115.7526
rx=-0.48488 ry=-0.02436 rz=-0.41321 s=-0.540645
step proj=cart inv ellps=GRS80
The pipeline can be expanded at both ends to accommodate whatever coordinate type is needed for input and output:
In the example below, we transform from the deprecated Danish System 45, a 2D system with some tension in the
original defining network, to UTM zone 33, ETRS89. The tension is reduced using a polynomial transformation (the
init=./s45b. . . step, s45b.pol is a file containing the polynomial coefficients), taking the S45 coordinates to a technical
coordinate system (TC32), defined to represent “UTM zone 32 coordinates, as they would look if the Helmert transfor-
mation between ED50 and ETRS89 was perfect”. The TC32 coordinates are then converted back to geodetic(ED50)
coordinates, using an inverse UTM projection, further to cartesian(ED50), then to cartesian(ETRS89), using the rel-
evant Helmert transformation, and back to geodetic(ETRS89), before finally being projected onto the UTM zone 33,
ETRS89 system. All in all a 6 step pipeline, implementing a transformation with centimeter level accuracy from a
deprecated system with decimeter level tensions.
proj=pipeline
step init=./s45b.pol:s45b_tc32
step proj=utm inv ellps=intl zone=32
step proj=cart ellps=intl
step proj=helmert
x=-81.0703 y=-89.3603 z=-115.7526
rx=-0.48488 ry=-0.02436 rz=-0.41321 s=-0.540645
(continues on next page)
4.3. Geodetic transformation 13

(continued from previous page)

step proj=cart inv ellps=GRS80
step proj=utm ellps=GRS80 zone=33
With the pipeline framework spatiotemporal transformation is possible. This is possible by leveraging the time di-
mension in PROJ that enables 4D coordinates (three spatial components and one temporal component) to be passed
through a transformation pipeline. In the example below a transformation from ITRF93 to ITRF2000 is defined. The
temporal component is given as GPS weeks in the input data, but the 14-parameter Helmert transform expects tem-
poral units in decimalyears. Hence the first step in the pipeline is the unitconvert pseudo-projection that makes sure
the correct units are passed along to the Helmert transform. Most parameters of the Helmert transform are taken from
[AltamimiEtAl2002], except the epoch which is the epoch of the transformation. The default setting is to use “coordi-
nate frame” convention of the Helmert transform, but “position vector” convention can also be used. The last step in
the pipeline is converting the coordinate timestamps back to GPS weeks.
proj=pipeline
step proj=unitconvert t_in=gps_week t_out=decimalyear
step proj=helmert
x=0.0127 y=0.0065 z=-0.0209 s=0.00195
rx=0.00039 ry=-0.00080 rz=0.00114
dx=-0.0029 dy=-0.0002 dz=-0.0006 ds=0.00001
drx=0.00011 dry=0.00019 drz=-0.00007
t_epoch=1988.0
step proj=unitconvert t_in=decimalyear t_out=gps_week
4.3.2 cs2cs paradigm
Parameter Description
+datum Datum name (see proj -ld)
+geoidgrids Filename of GTX grid file to use for vertical datum transforms
+nadgrids Filename of NTv2 grid file to use for datum transforms
+towgs84 3 or 7 term datum transform parameters
+to_meter Multiplier to convert map units to 1.0m
+vto_meter Vertical conversion to meters
The cs2cs framework delivers a subset of the geodetic transformations available with the pipeline framework. Coordi-
nate transformations done in this framework are transformed in a two-step process with WGS84 as a pivot datum That
is, the input coordinates are transformed to WGS84 geodetic coordinates and then transformed from WGS84 coordi-
nates to the specified output coordinate reference system, by utilizing either the Helmert transform, datum shift grids or
a combination of both. Datum shifts can be described in a proj-string with the parameters +towgs84, +nadgrids
and +geoidgrids. An inverse transform exists for all three and is applied if specified in the input proj-string. The
most common is +towgs84, which is used to define a 3- or 7-parameter Helmert shift from the input reference frame
to WGS84. Exactly which realization of WGS84 is not specified, hence a fair amount of uncertainty is introduced in
this step of the transformation. With the +nadgrids parameter a non-linear planar correction derived from interpolation
in a correction grid can be applied. Originally this was implemented as a means to transform coordinates between the
North American datums NAD27 and NAD83, but corrections can be applied for any datum for which a correction grid
exists. The inverse transform for the horizontal grid shift is “dumb”, in the sense that the correction grid is applied
verbatim without taking into account that the inverse operation is non-linear. Similar to the horizontal grid correction,
+geoidgrids can be used to perform grid corrections in the vertical component. Both grid correction methods
allow inclusion of more than one grid in the same transformation
In contrast to the transformation pipeline framework, transformations with the cs2cs framework are expressed as two
separate proj-strings. One proj-string to WGS84 and one from WGS84. Together they form the mapping from the

source coordinate reference system to the destination coordinate reference system. When used with the cs2cs the
source and destination CRS’s are separated by the special +to parameter.
The following example demonstrates converting from the Greek GGRS87 datum to WGS84 with the +towgs84
parameter.
cs2cs +proj=latlong +ellps=GRS80 +towgs84=-199.87,74.79,246.62

+to +proj=latlong +datum=WGS84
20 35
20d0'5.467"E 35d0'9.575"N 8.570
The EPSG database provides this example for transforming from WGS72 to WGS84 using an approximated 7 param-
eter transformation.
cs2cs +proj=latlong +ellps=WGS72 +towgs84=0,0,4.5,0,0,0.554,0.219 \

+to +proj=latlong +datum=WGS84
4 55
4d0'0.554"E 55d0'0.09"N 3.223
4.3.3 Grid Based Datum Adjustments
In many places (notably North America and Australia) national geodetic organizations provide grid shift files for
converting between different datums, such as NAD27 to NAD83. These grid shift files include a shift to be applied at
each grid location. Actually grid shifts are normally computed based on an interpolation between the containing four
grid points.
PROJ supports use of grid files for shifting between various reference frames. The grid shift table formats are ctable
(the binary format produced by the PROJ nad2bin program), NTv1 (the old Canadian format), and NTv2 (.gsb -
the new Canadian and Australian format).
The text in this section is based on the cs2cs framework. Gridshifting is off course also possible with the pipeline
framework. The major difference between the two is that the cs2cs framework is limited to grid mappings to WGS84,
whereas with transformation pipelines it is possible to perform grid shifts between any two reference frames, as long
as a grid exists.
Use of grid shifts with cs2cs is specified using the +nadgrids keyword in a coordinate system definition. For
example:
% cs2cs +proj=latlong +ellps=clrk66 +nadgrids=ntv1_can.dat \

+to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
-111 50
EOF
111d0'2.952"W 50d0'0.111"N 0.000
In this case the /usr/local/share/proj/ntv1_can.dat grid shift file was loaded, and used to get a grid
shift value for the selected point.
It is possible to list multiple grid shift files, in which case each will be tried in turn till one is found that contains the
point being transformed.
cs2cs +proj=latlong +ellps=clrk66 \

+nadgrids=conus,alaska,hawaii,stgeorge,stlrnc,stpaul \
-111 44
EOF
111d0'2.788"W 43d59'59.725"N 0.000
4.3. Geodetic transformation 15

Skipping Missing Grids
The special prefix @ may be prefixed to a grid to make it optional. If it not found, the search will continue to the next
grid. Normally any grid not found will cause an error. For instance, the following would use the ntv2_0.gsb file if
available (see Non-Free Grids), otherwise it would fallback to using the ntv1_can.dat file.
cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb,ntv1_can.dat \

-111 50
EOF
111d0'3.006"W 50d0'0.103"N 0.000
The null Grid
A special null grid shift file is shift with releases after 4.4.6 (not inclusive). This file provides a zero shift for the
whole world. It may be listed at the end of a nadgrids file list if you want a zero shift to be applied to points outside
the valid region of all the other grids. Normally if no grid is found that contains the point to be transformed an error
will occur.
cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \

-111 45
EOF
111d0'3.006"W 50d0'0.103"N 0.000
cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \

-111 44
-111 55
EOF
111d0'2.788"W 43d59'59.725"N 0.000
111dW 55dN 0.000
For more information see the chapter on Transformation grids.
Caveats
• Where grids overlap (such as conus and ntv1_can.dat for instance) the first found for a point will be used
regardless of whether it is appropriate or not. So, for instance, +nadgrids=ntv1_can.dat,conus would
result in the Canadian data being used for some areas in the northern United States even though the conus data is
the approved data to use for the area. Careful selection of files and file order is necessary. In some cases border
spanning datasets may need to be pre-segmented into Canadian and American points so they can be properly
grid shifted
• There are additional grids for shifting between NAD83 and various HPGN versions of the NAD83 datum. Use
of these haven’t been tried recently so you may encounter problems. The FL.lla, WO.lla, MD.lla, TN.lla and
WI.lla are examples of high precision grid shifts. Take care!
• Additional detail on the grid shift being applied can be found by setting the PROJ_DEBUG environment variable
to a value. This will result in output to stderr on what grid is used to shift points, the bounds of the various grids
loaded and so forth
• The cs2cs framework always assumes that grids contain a shift to NAD83 (essentially WGS84). Other types of
grids can be used with the pipeline framework.

4.4 Environment variables
PROJ can be controlled by setting environment variables. Most users will have a use for the PROJ_LIB.
On UNIX systems environment variables can be set for a shell-session with:
$ export VAR="some variable"
or it can be set for just one command line call:
$ VAR="some variable" ./cmd
Environment variables on UNIX are usually removed with the unset command:
$ unset VAR
On windows systems environment variables can be set in the command line with:
> set VAR="some variable"
`VAR will be available for the entire session, unless it is unset. This is done by setting the variable with no content:
> set VAR=
PROJ_LIB
The location of PROJ resource files. It is only possible to specify a single library in PROJ_LIB; e.g. it does not
behave like PATH. PROJ is hardcoded to look for resource files in other locations as well, amongst those are the
users home directory, /usr/share/proj and the current folder.
PROJ_DEBUG
Set the debug level of PROJ. The default debug level is zero, which results in no debug output when using PROJ.
A number from 1-3, whit 3 being the most verbose setting.
4.5 Known differences between versions
Once in a while, a new version of PROJ causes changes in the existing behaviour. In this section we track deliberate
changes to PROJ that break from previous behaviour. Most times that will be caused by a bug fix. Unfortunately, some
bugs have existed for so long that their faulty behaviour is relied upon by software that uses PROJ.
Behavioural changes caused by new bugs are not tracked here, as they should be fixed in later versions of PROJ.
4.5.1 Version 5.0.0
Longitude wrapping when using custom central meridian
By default PROJ wraps output longitudes in the range -180 to 180. Previous to PROJ 5, this was handled incorrectly
when a custom central meridian was set with +lon_0. This caused a change in sign on the resulting easting as seen
below:
$ proj +proj=merc +lon_0=110

-70 0
-20037508.34 0.00
290 0
20037508.34 0.00
4.4. Environment variables 17

From PROJ 5 on onwards, the same input now results in same coordinates, as seen from the example below where
PROJ 5 is used:
$ proj +proj=merc +lon_0=110

-70 0
-20037508.34 0.00
290 0
-20037508.34 0.00
The change is made on the basis that 𝜆 = 290∘ is a full rotation of the circle larger than 𝜆 = −70∘ and hence should
return the same output for both.
Adding the +over flag to the projection definition provides the old behaviour.

CHAPTER
FIVE
APPLICATIONS
Bundled with PROJ comes a set of small command line utilities. The proj program is limited to converting between
geographic and projection coordinates within one datum. The cs2cs program operates similarly, but allows trans-
lation between any pair of definable coordinate systems, including support for basic datum translation. The geod
program provides the ability to do geodesic (great circle) computations. gie is the program used for regression tests
in PROJ.
5.1 proj
5.1.1 Synopsis
proj [ -beEfiIlmorsStTvVwW ] [ args ] ] [ +args ] file[s]

invproj [ -beEfiIlmorsStTvVwW ] [ args ] ] [ +args ] file[s]
5.1.2 Description
proj and invproj perform respective forward and inverse transformation of cartographic data to or from cartesian
data with a wide range of selectable projection functions.
invproj may not be available on all platforms; in this case use proj -I instead.
The following control parameters can appear in any order
-b
Special option for binary coordinate data input and output through standard input and standard output. Data
is assumed to be in system type double floating point words. This option is to be used when proj is a child
process and allows bypassing formatting operations.
-i
Selects binary input only (see -b).
-I
Alternate method to specify inverse projection. Redundant when used with invproj.
-o
Selects binary output only (see -b).
-t<a>
Where a specifies a character employed as the first character to denote a control line to be passed through without
processing. This option applicable to ASCII input only. (# is the default value).
19
-e <string>
Where string is an arbitrary string to be output if an error is detected during data transformations. The default
value is a three character string: *\t*. Note that if the -b, -i or -o options are employed, an error is returned
as HUGE_VAL value for both return values.
-E
Causes the input coordinates to be copied to the output line prior to printing the converted values.
-l<[=id]>
List projection identifiers that can be selected with +proj. proj -l=id gives expanded description of projec-
tion id, e.g. proj -l=merc.
-lp
List of all projection id that can be used with the +proj parameter. Equivalent to proj -l.
-lP
Expanded description of all projections that can be used with the +proj parameter.
-le
List of all ellipsoids that can be selected with the +ellps parameters.
-lu
List of all distance units that can be selected with the +units parameter.
-ld
List of datums that can be selected with the +datum parameter.
-r
This options reverses the order of the expected input from longitude-latitude or x-y to latitude-longitude or y-x.
-s
This options reverses the order of the output from x-y or longitude-latitude to y-x or latitude-longitude.
-S
Causes estimation of meridional and parallel scale factors, area scale factor and angular distortion, and maximum
and minimum scale factors to be listed between <> for each input point. For conformal projections meridional
and parallel scales factors will be equal and angular distortion zero. Equal area projections will have an area
factor of 1.
-m <mult>
The cartesian data may be scaled by the mult parameter. When processing data in a forward projection mode the
cartesian output values are multiplied by mult otherwise the input cartesian values are divided by mult before
inverse projection. If the first two characters of mult are 1/ or 1: then the reciprocal value of mult is employed.
-f <format>
Where format is a printf format string to control the form of the output values. For inverse projections, the
output will be in degrees when this option is employed. The default format is "%.2f" for forward projection
and DMS for inverse.
-w<n>
Where n is the number of significant fractional digits to employ for seconds output (when the option is not
specified, -w3 is assumed).
-W<n>
Where n is the number of significant fractional digits to employ for seconds output. When -W is employed the
fields will be constant width with leading zeroes.
-v
Causes a listing of cartographic control parameters tested for and used by the program to be printed prior to
input data. Should not be used with the -T option.
20 Chapter 5. Applications
-V
This option causes an expanded annotated listing of the characteristics of the projected point. -v is implied
with this option.
-T <ulow,uhi,vlow,vhi,res[,umax,vmax]>
This option creates a set of bivariate Chebyshev polynomial coefficients that approximate the selected carto-
graphic projection on stdout. The values low and hi denote the range of the input where the u or v prefixes
apply to respective longitude-x or latitude-y depending upon whether a forward or inverse projection is selected.
The integer res is a number specifying the power of 10 precision of the approximation. For example, a res of
-3 specifies an approximation with an accuracy better than 0.001. Optional umax, and vmax specify maximum
degree of the polynomials (default: 15).
The +args run-line arguments are associated with cartographic parameters. Additional projection control parameters
may be contained in two auxiliary control files: the first is optionally referenced with the +init=file:id and the second
is always processed after the name of the projection has been established from either the run-line or the contents of
+init file. The environment parameter PROJ_LIB establishes the default directory for a file reference without an
absolute path. This is also used for supporting files like datum shift files.
One or more files (processed in left to right order) specify the source of data to be transformed. A - will specify the
location of processing standard input. If no files are specified, the input is assumed to be from stdin. For ASCII input
data the two data values must be in the first two white space separated fields and when both input and output are ASCII
all trailing portions of the input line are appended to the output line.
Input geographic data (longitude and latitude) must be in DMS format and input cartesian data must be in units
consistent with the ellipsoid major axis or sphere radius units. Output geographic coordinates will be in DMS (if the
-w switch is not employed) and precise to 0.001” with trailing, zero-valued minute-second fields deleted.
5.1.3 Example
The following script
proj +proj=utm +lon_0=112w +ellps=clrk66 -r <<EOF

45d15'33.1" 111.5W
45d15.551666667N -111d30
+45.25919444444 111d30'000w
EOF
will perform UTM forward projection with a standard UTM central meridian nearest longitude 112W. The geographic
values of this example are equivalent and meant as examples of various forms of DMS input. The x-y output data will
appear as three lines of:
460769.27 5011648.45
5.2 cct
5.2.1 Synopsis
cct [ -cIostvz [ args ] ] +opts[=arg] file[s]
5.2.2 Description
cct a 4D equivalent to the proj projection program, performs transformation coordinate systems on a set of input
points. The coordinate system transformation can include translation between projected and geographic coordinates
5.2. cct 21
as well as the application of datum shifts.

The following control parameters can appear in any order:
-c <x,y,z,t>
Specify input columns for (up to) 4 input parameters. Defaults to 1,2,3,4.
-I
Do the inverse transformation.
-o <output file name>, --output=<output file name>
Specify the name of the output file.
-t <time>, --time=<time>
Specify a fixed observation time to be used for all input data.
-z <height>, --height=<height>
Specify a fixed observation height to be used for all input data.
-s <n>, --skip-lines=<n>
New in version 5.1.0.
Skip the first n lines of input. This applies to any kind of input, whether it comes from STDIN, a file or
interactive user input.
-v, --verbose
Write non-essential, but potentially useful, information to stderr. Repeat for additional information (-vv, -vvv,
etc.)
--version
Print version number.
The +args arguments are associated with coordinate operation parameters. Usage varies with operation.
cct is an acronym meaning Coordinate Conversion and Transformation.
The acronym refers to definitions given in the OGC 08-015r2/ISO-19111 standard “Geographical Information – Spatial
Referencing by Coordinates”, which defines two different classes of coordinate operations:
Coordinate Conversions, which are coordinate operations where input and output datum are identical (e.g. conversion
from geographical to cartesian coordinates) and
Coordinate Transformations, which are coordinate operations where input and output datums differ (e.g. change of
reference frame).
5.2.3 Examples
1. The operator specs describe the action to be performed by cct. So the following script
echo 12 55 0 0 | cct +proj=utm +zone=32 +ellps=GRS80
will transform the input geographic coordinates into UTM zone 32 coordinates. Hence, the command
echo 12 55 | cct -z0 -t0 +proj=utm +zone=32 +ellps=GRS80
Should give results comparable to the classic proj command
echo 12 55 | proj +proj=utm +zone=32 +ellps=GRS80
2. Convert geographical input to UTM zone 32 on the GRS80 ellipsoid:
cct +proj=utm +ellps=GRS80 +zone=32
3. Roundtrip accuracy check for the case above:
cct +proj=pipeline +proj=utm +ellps=GRS80 +zone=32 +step +step +inv
4. As (2) but specify input columns for longitude, latitude, height and time:
cct -c 5,2,1,4 +proj=utm +ellps=GRS80 +zone=32
5. As (2) but specify fixed height and time, hence needing only 2 cols in input:
cct -t 0 -z 0 +proj=utm +ellps=GRS80 +zone=32
5.2.4 Background
cct also refers to Carl Christian Tscherning (1942–2014), professor of Geodesy at the University of Copenhagen,
mentor and advisor for a generation of Danish geodesists, colleague and collaborator for two generations of global
geodesists, Secretary General for the International Association of Geodesy, IAG (1995–2007), fellow of the American
Geophysical Union (1991), recipient of the IAG Levallois Medal (2007), the European Geosciences Union Vening
Meinesz Medal (2008), and of numerous other honours.
cct, or Christian, as he was known to most of us, was recognized for his good mood, his sharp wit, his tireless work,
and his great commitment to the development of geodesy – both through his scientific contributions, comprising more
than 250 publications, and by his mentoring and teaching of the next generations of geodesists.
As Christian was an avid Fortran programmer, and a keen Unix connoisseur, he would have enjoyed to know that his
initials would be used to name a modest Unix style transformation filter, hinting at the tireless aspect of his personality,
which was certainly one of the reasons he accomplished so much, and meant so much to so many people.
Hence, in honour of cct (the geodesist) this is cct (the program).
5.3 cs2cs
5.3.1 Synopsis
cs2cs [ -eEfIlrstvwW [ args ] ] [ +opts[=arg] ] [ +to [+opts[=arg]] ] file[s]
5.3.2 Description
cs2cs performs transformation between the source and destination cartographic coordinate system on a set of input
points. The coordinate system transformation can include translation between projected and geographic coordinates
as well as the application of datum shifts.
The following control parameters can appear in any order:
-I
Method to specify inverse translation, convert from +to coordinate system to the primary coordinate system
defined.
-t<a>
processing. This option applicable to ASCII input only. (# is the default value).
5.3. cs2cs 23
-e <string>
Where string is an arbitrary string to be output if an error is detected during data transformations. The default
value is a three character string: *\t*.
-E
Causes the input coordinates to be copied to the output line prior to printing the converted values.
-l<[=id]>
List projection identifiers that can be selected with +proj. cs2cs -l=id gives expanded description of pro-
jection id, e.g. cs2cs -l=merc.
-lp
List of all projection id that can be used with the +proj parameter. Equivalent to cs2cs -l.
-lP
Expanded description of all projections that can be used with the +proj parameter.
-le
List of all ellipsoids that can be selected with the +ellps parameters.
-lu
List of all distance units that can be selected with the +units parameter.
-ld
List of datums that can be selected with the +datum parameter.
-r
This options reverses the order of the expected input from longitude-latitude or x-y to latitude-longitude or y-x.
-s
This options reverses the order of the output from x-y or longitude-latitude to y-x or latitude-longitude.
-f <format>
Where format is a printf format string to control the form of the output values. For inverse projections, the
output will be in degrees when this option is employed. If a format is specified for inverse projection the output
data will be in decimal degrees. The default format is "%.2f" for forward projection and DMS for inverse.
-w<n>
-W<n>
-v
Causes a listing of cartographic control parameters tested for and used by the program to be printed prior to
input data.
The cs2cs program requires two coordinate system definitions. The first (or primary is defined based on all pro-
jection parameters not appearing after the +to argument. All projection parameters appearing after the +to argument
are considered the definition of the second coordinate system. If there is no second coordinate system defined, a geo-
graphic coordinate system based on the datum and ellipsoid of the source coordinate system is assumed. Note that the
source and destination coordinate system can both be projections, both be geographic, or one of each and may have
the same or different datums.
Additional projection control parameters may be contained in two auxiliary control files: the first is optionally refer-
enced with the +init=file:id and the second is always processed after the name of the projection has been established
from either the run-line or the contents of +init file. The environment parameter PROJ_LIB establishes the default
directory for a file reference without an absolute path. This is also used for supporting files like datum shift files.
location of processing standard input. If no files are specified, the input is assumed to be from stdin. For input data
the two data values must be in the first two white space separated fields and when both input and output are ASCII all
trailing portions of the input line are appended to the output line.
Input geographic data (longitude and latitude) must be in DMS or decimal degrees format and input cartesian data
must be in units consistent with the ellipsoid major axis or sphere radius units. Output geographic coordinates will
normally be in DMS format (use -f %.12f for decimal degrees with 12 decimal places), while projected (cartesian)
coordinates will be in linear (meter, feet) units.
5.3.3 Example
The following script
cs2cs +proj=latlong +datum=NAD83 +to +proj=utm +zone=10 +datum=NAD27 -r <<EOF

45d15'33.1" 111.5W
45d15.551666667N -111d30
+45.25919444444 111d30'000w
EOF
will transform the input NAD83 geographic coordinates into NAD27 coordinates in the UTM projection with zone 10
selected. The geographic values of this example are equivalent and meant as examples of various forms of DMS input.
The x-y output data will appear as three lines of:
1402285.99 5076292.42 0.000
5.4 geod
5.4.1 Synopsis
geod +ellps=<ellipse> [ -afFIlptwW [ args ] ] [ +args ] file[s]

invgeod +ellps=<ellipse> [ -afFIlptwW [ args ] ] [ +args ] file[s]
5.4.2 Description
geod (direct) and invgeod (inverse) perform geodesic (Great Circle) computations for determining latitude, longi-
tude and back azimuth of a terminus point given a initial point latitude, longitude, azimuth and distance (direct) or the
forward and back azimuths and distance between an initial and terminus point latitudes and longitudes (inverse). The
results are accurate to round off for |𝑓 | < 1/50, where 𝑓 is flattening.
invgeod may not be available on all platforms; in this case use geod -I instead.
The following command-line options can appear in any order:
-I
Specifies that the inverse geodesic computation is to be performed. May be used with execution of geod as an
alternative to invgeod execution.
-a
Latitude and longitudes of the initial and terminal points, forward and back azimuths and distance are output.
5.4. geod 25
-t<a>
processing.
-le
Gives a listing of all the ellipsoids that may be selected with the +ellps= option.
-lu
Gives a listing of all the units that may be selected with the +units= option.
-f <format>
Where format is a printf format string to control the output form of the geographic coordinate values. The
default mode is DMS for geographic coordinates and "%.3f" for distance.
-F <format>
Where format is a printf format string to control the output form of the distance value (-F). The default mode is
DMS for geographic coordinates and "%.3f" for distance.
-w<n>
-W<n>
-p
This option causes the azimuthal values to be output as unsigned DMS numbers between 0 and 360 degrees.
Also note -f.
The +args 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. Reentry of an option is ignored
with the first occurrence assumed to be the desired value.
location of processing standard input. If no files are specified, the input is assumed to be from stdin.
For direct determinations input data must be in latitude, longitude, azimuth and distance order and output will be
latitude, longitude and back azimuth of the terminus point. Latitude, longitude of the initial and terminus point are
input for the inverse mode and respective forward and back azimuth from the initial and terminus points are output
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 will be in DMS (if the -f switch is not employed) 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.
The Earth’s ellipsoidal figure may be selected in the same manner as program proj by using +ellps=, +a=, +es=,
etc.
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=lon parameters and either a terminus point +lat_2=lat and +lon_2=lon or a distance and azimuth from the
initial point with +S=distance and +A=azimuth must be specified.
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.
5.4.3 Examples
The following script determines the geodesic azimuths and distance in U.S. statute miles from Boston, MA, to Portland,
OR:
geod +ellps=clrk66 <<EOF -I +units=us-mi

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.
An example of forward geodesic use is to use the Boston location and determine Portland’s location by azimuth and
distance:
geod +ellps=clrk66 <<EOF +units=us-mi

42d15'N 71d07'W -66d31'50.141" 2587.504
EOF
which gives:
45d31'0.003"N 123d40'59.985"W 75d39'13.094"
Note: Lack of precision in the distance value compromises the precision of the Portland location.
5.4.4 Further reading
1. GeographicLib.
2. C. F. F. Karney, Algorithms for Geodesics, J. Geodesy 87(1), 43–55 (2013); addenda.
3. A geodesic bibliography.
5.5 gie
5.5.1 Synopsis
gie [ -hovql [ args ] ] file[s]
5.5.2 Description
gie, the Geospatial Integrity Investigation Environment, is a regression testing environment for the PROJ transforma-
tion library. Its primary design goal is to be able to perform regression testing of code that are a part of PROJ, while
not requiring any other kind of tooling than the same C compiler already employed for compiling the library.
-h, --help
Print usage information
5.5. gie 27
-o <file>, --output <file>

Specify output file name
-v, --verbose
Verbose: Provide non-essential informational output. Repeat -v for more verbosity (e.g. -vv)
-q, --quiet
Quiet: Opposite of verbose. In quiet mode not even errors are reported. Only interaction is through the return
code (0 on success, non-zero indicates number of FAILED tests)
-l, --list
List the PROJ internal system error codes
--version
Print version number
Tests for gie are defined in simple text files. Usually having the extension .gie. Test for gie are written in
the purpose-build command language for gie. The basic functionality of the gie command language is implemented
through just 3 command verbs: operation, which defines the PROJ operation to test, accept, which defines the
input coordinate to read, and expect, which defines the result to expect.
A sample test file for gie that uses the three above basic commands looks like:
<gie>
--------------------------------------------
Test output of the UTM projection
--------------------------------------------
operation +proj=utm +zone=32 +ellps=GRS80
--------------------------------------------
accept 12 55
expect 691_875.632_14 6_098_907.825_05
</gie>
Parsing of a gie file starts at <gie> and ends when </gie> is reached. Anything before <gie> and after </gie>
is not considered. Test cases are created by defining an operation which accept an input coordinate and expect
an output coordinate.
Because gie tests are wrapped in the <gie>/</gie> tags it is also possible to add test cases to custom made init
files. The tests will be ignore by PROJ when reading the init file with +init and gie ignores anything not wrapped in
<gie>/</gie>.
gie tests are defined by a set of commands like operation, accept and expect in the example above. Together
the commands make out the gie command language. Any line in a gie file that does not start with a command is
ignored. In the example above it is seen how this can be used to add comments and styling to gie test files in order to
make them more readable as well as documenting what the purpose of the various tests are.
Below the gie command language is explained in details.
5.5.3 Examples
1. Run all tests in a file with all debug information turned on
gie -vvvv corner-cases.gie
2. Run all tests in several files
gie foo bar
5.5.4 gie command language
operation <+args>
Define a PROJ operation to test. Example:
operation proj=utm zone=32 ellps=GRS80

# test 4D function
accept 12 55 0 0
expect 691875.63214 6098907.82501 0 0
# test 2D function
accept 12 56
expect 687071.4391 6210141.3267
accept <x y [z [t]]>

Define the input coordinate to read. Takes test coordinate. The coordinate can be defined by either 2, 3 or 4
values, where the first two values are the x- and y-components, the 3rd is the z-component and the 4th is the time
component. The number of components in the coordinate determines which version of the operation is tested
(2D, 3D or 4D). Many coordinates can be accepted for one operation. For each accept an accompanying
expect is needed.
Note that gie accepts the underscore (_) as a thousands separator. It is not required (in fact, it is entirely ignored
by the input routine), but it significantly improves the readability of the very long strings of numbers typically
required in projected coordinates.
See operation for an example.
expect <x y [z [t]]> | <error code>
Define the expected coordinate that will be returned from accepted coordinate passed though an operation. The
expected coordinate can be defined by either 2, 3 or 4 components, similarly to accept. Many coordinates can
be expected for one operation. For each expect an accompanying accept is needed.
See operation for an example.
In addition to expecting a coordinate it is also possible to expect a PROJ error code in case an operation can’t
be created. This is useful when testing that errors are caught and handled correctly. Below is an example of that
tests that the pipeline operator fails correctly when a non-invertible pipeline is constructed.
operation proj=pipeline step

proj=urm5 n=0.5 inv
expect failure pjd_err_malformed_pipeline
See gie -l for a list of error codes that can be expected.

tolerance <tolerance>
The tolerance command controls how much accepted coordinates can deviate from the expected coordinate.
This is handy to test that an operation meets a certain numerical tolerance threshold. Some operations are ex-
pected to be accurate within millimeters where others might only be accurate within a few meters. tolerance
should
operation proj=merc
# test coordinate as returned by ```echo 12 55 | proj +proj=merc``
tolerance 1 cm
accept 12 55
5.5. gie 29

expect 1335833.89 7326837.72
# test that the same coordinate with a 50 m false easting as determined

# by ``echo 12 55 |proj +proj=merc +x_0=50`` is still within a 100 m
# tolerance of the unaltered coordinate from proj=merc
tolerance 100 m
accept 12 55
expect 1335883.89 7326837.72
The default tolerance is 0.5 mm. See proj -lu for a list of possible units.
roundtrip <n> <tolerance>
Do a roundtrip test of an operation. roundtrip needs a operation and a accept command to function.
The accepted coordinate is passed to the operation first in it’s forward mode, then the output from the forward
operation is passed back to the inverse operation. This procedure is done n times. If the resulting coordinate is
within the set tolerance of the initial coordinate, the test is passed.
Example with the default 100 iterations and the default tolerance:
operation proj=merc
accept 12 55
roundtrip
Example with count and default tolerance:

operation proj=merc
accept 12 55
roundtrip 10000
Example with count and tolerance:

operation proj=merc
accept 12 55
roundtrip 10000 5 mm
direction <direction>
The direction command specifies in which direction an operation is performed. This can either be forward
or inverse. An example of this is seen below where it is tested that a symmetrical transformation pipeline
returns the same results in both directions.
operation proj=pipeline zone=32 step
proj=utm ellps=GRS80 step
proj=utm ellps=GRS80 inv
tolerance 0.1 mm
accept 12 55 0 0
expect 12 55 0 0
# Now the inverse direction (still same result: the pipeline is symmetrical)
direction inverse
expect 12 55 0 0
The default direction is “forward”.

ignore <error code>
This is especially useful in test cases that rely on a grid that is not guaranteed to be available. Below is an
example of that situation.
operation proj=hgridshift +grids=nzgd2kgrid0005.gsb ellps=GRS80

tolerance 1 mm
ignore pjd_err_failed_to_load_grid
accept 172.999892181021551 -45.001620431954613
expect 173 -45
See gie -l for a list of error codes that can be ignored.

echo <text>
Add user defined text to the output stream. See the example below.
<gie>
echo ** Mercator projection tests **
operation +proj=merc
accept 0 0
expect 0 0
</gie>
which returns
-------------------------------------------------------------------------------
Reading file 'test.gie'
** Mercator projection test **
-------------------------------------------------------------------------------
total: 1 tests succeeded, 0 tests skipped, 0 tests failed.
-------------------------------------------------------------------------------
skip
Skip any test after the first occurrence of skip. In the example below only the first test will be performed. The
second test is skipped. This feature is mostly relevant for debugging when writing new test cases.
<gie>
operation proj=merc
accept 0 0
expect 0 0
skip
accept 0 1
expect 0 110579.9
</gie>
5.5.5 Background
More importantly than being an acronym for “Geospatial Integrity Investigation Environment”, gie were also the
initials, user id, and USGS email address of Gerald Ian Evenden (1935–2016), the geospatial visionary, who, already
in the 1980s, started what was to become the PROJ of today.
Gerald’s clear vision was that map projections are just special functions. Some of them rather complex, most of them
of two variables, but all of them just special functions, and not particularly more special than the sin(), cos(),
tan(), and hypot() already available in the C standard library.
And hence, according to Gerald, they should not be particularly much harder to use, for a programmer, than the
sin()’s, tan()’s and hypot()’s so readily available.
Gerald’s ingenuity also showed in the implementation of the vision, where he devised a comprehensive, yet simple,
system of key-value pairs for parameterising a map projection, and the highly flexible PJ struct, storing run-time
compiled versions of those key-value pairs, hence making a map projection function call, pj_fwd(PJ, point),
as easy as a traditional function call like hypot(x,y).
5.5. gie 31
While today, we may have more formally well defined metadata systems (most prominent the OGC WKT2 representa-
tion), nothing comes close being as easily readable (“human compatible”) as Gerald’s key-value system. This system
in particular, and the PROJ system in general, was Gerald’s great gift to anyone using and/or communicating about
geodata.
It is only reasonable to name a program, keeping an eye on the integrity of the PROJ system, in honour of Gerald.
So in honour, and hopefully also in the spirit, of Gerald Ian Evenden (1935–2016), this is the Geospatial Integrity
Investigation Environment.
CHAPTER
SIX
COORDINATE OPERATIONS
Coordinate operations in PROJ are divided into three groups: Projections, conversions and transformations. Projec-
tions are purely cartographic mappings of the sphere onto the plane. Technically projections are conversions (according
to ISO standards), though in PROJ projections are distinguished from conversions. Conversions are coordinate oper-
ations that do not exert a change in reference frame. Operations that do exert a change in reference frame are called
transformations.
6.1 Projections
Projections are coordinate operations that are technically conversions but since projections are so fundamental to PROJ
we differentiate them from conversions.
Projections map the spherical 3D space to a flat 2D space.
6.1.1 Albers Equal Area
Classification Conic
Available forms Forward and inverse, spherical and elliptical projection
Defined area Global
Alias aea
Domain 2D
Input type Geodetic coordinates
Output type Projected coordinates
33
Options
Note: All options are optional for the Albers Equal Area projection.
+lat_1=<value>
First standard parallel.
Defaults to 0.0.
+lat_2=<value>
Second standard parallel.
Defaults to 0.0.
+lon_0=<value>
Longitude of projection center.
Defaults to 0.0.
+ellps=<value>
See proj -le for a list of available ellipsoids.
Defaults to “WGS84”.
+R=<value>
Radius of the sphere given in meters. If used in conjunction with +ellps +R takes precedence.
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
34 Chapter 6. Coordinate operations

6.1.2 Azimuthal Equidistant
Classification Azimuthal
Alias aeqd
Domain 2D
Options
Note: All options are optional for the Azimuthal Equidistant projection.
+guam
Use Guam elliptical formulas. Only accurate near the Island of Guam (𝜆 ≈ 144.5∘ , 𝜑 ≈ 13.5∘ )
+k_0=<value>
Scale factor. Determines scale factor used in the projection.
Defaults to 1.0.
+lat_ts=<value>
Latitude of true scale. Defines the latitude where scale is not distorted. Takes precedence over +k_0 if both
options are used together.
Defaults to 0.0.
+lat_0=<value>
Latitude of projection center.
Defaults to 0.0.
+lon_0=<value>
6.1. Projections 35
Defaults to 0.0.
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
+ellps=<value>
+R=<value>
6.1.3 Airy
The Airy projection is an azimuthal minimum error projection for the region within the small or great circle defined
by an angular distance, 𝜑𝑏 , from the tangency point of the plane (𝜆0 , 𝜑0 ).
Available forms Forward spherical projection
Defined area Global
Alias airy
Domain 2D

Options
+lat_b
Angular distance from tangency point of the plane (𝜆0 , 𝜑0 ) where the error is kept at minimum.
Defaults to 90° (suitable for hemispherical maps).
+no_cut
Do not cut at hemisphere limit
+lat_0=<value>
Defaults to 0.0.
+lon_0=<value>
Defaults to 0.0.
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
+R=<value>
6.1.4 Aitoff
Classification Miscellaneous
Available forms Forward and inverse spherical projection
Defined area Global
Alias aitoff
Domain 2D
6.1. Projections 37
Parameters
Note: All parameters for the projection are optional.
+lon_0=<value>
Defaults to 0.0.
+R=<value>
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
6.1.5 Modified Stererographics of Alaska
Classification Modified azimuthal

Defined area Alaska
Alsk alsk
Domain 2D

Options
Note: All options are optional for the projection.
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
+ellps=<value>
+R=<value>
6.1.6 Apian Globular I
Available forms Forward spherical projection
Defined area Global
Alias apian
Domain 2D
6.1. Projections 39
Options
Note: All options are optional for the Apian Globular projection.
+lat_0=<value>
Defaults to 0.0.
+lon_0=<value>
Defaults to 0.0.
+R=<value>
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.

6.1.7 August Epicycloidal
6.1.8 Bacon Globular
6.1. Projections 41
6.1.9 Bipolar conic of western hemisphere
6.1.10 Boggs Eumorphic

6.1.11 Bonne (Werner lat_1=90)
6.1.12 Cal Coop Ocean Fish Invest Lines/Stations
The CalCOFI pseudo-projection is the line and station coordinate system of the California Cooperative Oceanic Fish-
eries Investigations program, known as CalCOFI, for sampling offshore of the west coast of the U.S. and Mexico.
Classification Conformal cylindrical

Defined area Only valid for the west coast of USA and Mexico
Alias calcofi
Domain 2D
The coordinate system is based on the Mercator projection with units rotated -30 degrees from the meridian so that they
are oriented with the coastline of the Southern California Bight and Baja California. Lines increase from Northwest
6.1. Projections 43
to Southeast. A unit of line is 12 nautical miles. Stations increase from inshore to offshore. A unit of station is equal
to 4 nautical miles. The rotation point is located at line 80, station 60, or 34.15 degrees N, -121.15 degrees W, and
is depicted by the red dot in the figure. By convention, the ellipsoid of Clarke 1866 is used to calculate CalCOFI
coordinates.
The CalCOFI program is a joint research effort by the U.S. National Oceanic and Atmospheric Administration, Uni-
versity of California Scripps Oceanographic Institute, and California Department of Fish and Game. Surveys have
been conducted for the CalCOFI program since 1951, creating one of the oldest and most scientifically valuable joint
oceanographic and fisheries data sets in the world. The CalCOFI line and station coordinate system is now used by
several other programs including the Investigaciones Mexicanas de la Corriente de California (IMECOCAL) program
offshore of Baja California. The figure depicts some commonly sampled locations from line 40 to line 156.7 and
offshore to station 120. Blue numbers indicate line (bottom) or station (left) numbers along the grid. Note that lines
spaced at approximate 3-1/3 intervals are commonly sampled, e.g., lines 43.3 and 46.7.
Usage
A typical forward CalCOFI projection would be from lon/lat coordinates on the Clark 1866 ellipsoid. For example:
proj +proj=calcofi +ellps=clrk66 -E <<EOF

-121.15 34.15
EOF
Output of the above command:
-121.15 34.15 80.00 60.00
The reverse projection from line/station coordinates to lon/lat would be entered as:
proj +proj=calcofi +ellps=clrk66 -I -E -f "%.2f" <<EOF

80.0 60.0
EOF
Output of the above command:
80.0 60.0 -121.15 34.15
Options
Note: All options are optional for the CalCOFI projection.
+ellps=<value>
+R=<value>
Mathematical definition
The algorithm used to make conversions is described in [EberHewitt1979] with a few corrections reported in
[WeberMoore2013].

Further reading
1. General information about the CalCOFI program

2. The Investigaciones Mexicanas de la Corriente de California
6.1.13 Cassini (Cassini-Soldner)
Although the Cassini projection has been largely replaced by the Transverse Mercator, it is still in limited use outside
the United States and was one of the major topographic mapping projections until the early 20th century.
Classification Transverse and oblique cylindrical

Available forms Forward and inverse, Spherical and Elliptical
Defined area Global, but best used near the central meridian with long, narrow areas
Alias cass
Domain 2D
Usage
There has been little usage of the spherical version of the Cassini, but the ellipsoidal Cassini-Soldner version was
adopted by the Ordnance Survey for the official survey of Great Britain during the second half of the 19th century
[Steers1970]. Many of these maps were prepared at a scale of 1:2,500. The Cassini-Soldner was also used for the
detailed mapping of many German states during the same period.
Example using EPSG 30200 (Trinidad 1903, units in clarke’s links):
$ echo 0.17453293 -1.08210414 | proj +proj=cass +lat_0=10.44166666666667 +lon_0=-61.

˓→33333333333334 +x_0=86501.46392051999 +y_0=65379.0134283 +a=6378293.645208759
˓→+b=6356617.987679838 +to_meter=0.201166195164 +no_defs
66644.94 82536.22
Example using EPSG 3068 (Soldner Berlin):
6.1. Projections 45
$ echo 13.5 52.4 | proj +proj=cass +lat_0=52.41864827777778 +lon_0=13.62720366666667

˓→+x_0=40000 +y_0=10000 +ellps=bessel +datum=potsdam +units=m +no_defs
31343.05 7932.76
Options
Note: All options are optional for the Cassini projection.
+lat_0=<value>
Defaults to 0.0.
+lon_0=<value>
Defaults to 0.0.
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
+ellps=<value>
+R=<value>
The formulas describing the Cassini projection are taken from Snyder’s [Snyder1987].
𝜑0 is the latitude of origin that match the center of the map (default to 0). It can be set with +lat_0.
Spherical form
Forward projection
𝑥 = arcsin(cos(𝜑) sin(𝜆))
𝑦 = arctan 2(tan(𝜑), cos(𝜆)) − 𝜑0

Inverse projection
𝜑 = arcsin(sin(𝑦 + 𝜑0 ) cos(𝑥))
𝜆 = arctan 2(tan(𝑥), cos(𝑦 + 𝜑0 ))
Elliptical form
Forward projection
𝑁 = (1 − 𝑒2 sin2 (𝜑))−1/2
𝑇 = tan2 (𝜑)
𝐴 = 𝜆 cos(𝜑)
𝑒2
𝐶= 𝑐𝑜𝑠2 (𝜑)
1 − 𝑒2
𝐴3 𝐴5
𝑥 = 𝑁 (𝐴 − 𝑇 − (8 − 𝑇 + 8𝐶)𝑇 )
6 120
𝐴2 𝐴4
𝑦 = 𝑀 (𝜑) − 𝑀 (𝜑0 ) + 𝑁 tan(𝜑)( + (5 − 𝑇 + 6𝐶) )
2 24
and M() is the meridional distance function.
Inverse projection
𝜑′ = 𝑀 −1 (𝑀 (𝜑0 ) + 𝑦)
if 𝜑′ = 𝜋
2 then 𝜑 = 𝜑′ and 𝜆 = 0
otherwise evaluate T and N above using 𝜑′ and
𝑅 = (1 − 𝑒2 )(1 − 𝑒2 𝑠𝑖𝑛2 𝜑′ )−3/2
𝐷 = 𝑥/𝑁
𝑁 𝐷2 𝐷4
𝜑 = 𝜑′ − tan 𝜑′ ( − (1 + 3𝑇 ) )
𝑅 2 24
3 5
(𝐷 − 𝑇 𝐷3 + (1 + 3𝑇 )𝑇 𝐷
15 )
𝜆=
cos 𝜑′
Further reading
1. Wikipedia
2. [Snyder1987]
3. EPSG, POSC literature pertaining to Coordinate Conversions and Transformations including Formulas
6.1. Projections 47
6.1.14 Central Cylindrical
6.1.15 Central Conic

This is central (centrographic) projection on cone tangent at :option:lat_1 latitude, identical with conic() projec-
tion from mapproj R package.
Classification Conic
Available forms Forward and inverse, spherical projection
Defined area Global, but best used near the standard parallel
Alias ccon
Domain 2D

Usage
This simple projection is rarely used, as it is not equidistant, equal-area, nor conformal.
An example of usage (and the main reason to implement this projection in proj4) is the ATPOL geobotanical grid of
Poland, developed in Institute of Botany, Jagiellonian University, Krakow, Poland in 1970s [Zajac1978]. The grid was
originally handwritten on paper maps and further copied by hand. The projection (together with strange Earth radius)
was chosen by its creators as the compromise fit to existing maps during first software development in DOS era. Many
years later it is still de facto standard grid in Polish geobotanical research.
The ATPOL coordinates can be achieved with with the following parameters:
+proj=ccon +lat_1=52 +lon_0=19 +axis=esu +a=6390000 +x_0=330000 +y_0=-350000
For more information see [Komsta2016] and [Verey2017].
Parameters
Required
+lat_1=<value>
Standard parallel of projection.
Optional
+lon_0=<value>
Defaults to 0.0.
+R=<value>
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
Forward projection
𝑟 = cot 𝜑0 − tan(𝜑 − 𝜑0 )
𝑥 = 𝑟 sin(𝜆 sin 𝜑0 )
𝑦 = cot 𝜑0 − 𝑟 cos(𝜆 sin 𝜑0 )
6.1. Projections 49
Inverse projection
𝑦 = cot 𝜑0 − 𝑦
√︀
𝜑 = 𝜑0 − tan−1 ( 𝑥2 + 𝑦 2 − cot 𝜑0 )
√︀
tan−1 𝑥2 + 𝑦 2
𝜆=
sin 𝜑0
Reference values
For ATPOL to WGS84 test, run the following script:
#!/bin/bash
cat << EOF | src/cs2cs -v -f "%E" +proj=ccon +lat_1=52 +lat_0=52 +lon_0=19 +axis=esu
˓→+a=6390000 +x_0=330000 +y_0=-350000 +to +proj=longlat +datum=WGS84 +no_defs
0 0
0 700000
700000 0
700000 700000
330000 350000
EOF
It should result with
1.384023E+01 5.503040E+01 0.000000E+00

1.451445E+01 4.877385E+01 0.000000E+00
2.478271E+01 5.500352E+01 0.000000E+00
2.402761E+01 4.875048E+01 0.000000E+00
1.900000E+01 5.200000E+01 0.000000E+00
Analogous script can be run for reverse test:
cat << EOF | src/cs2cs -v -f "%E" +proj=longlat +datum=WGS84 +no_defs +to +proj=ccon
˓→+lat_1=52 +lat_0=52 +lon_0=19 +axis=esu +a=6390000 +x_0=330000 +y_0=-350000
24 55
15 49
24 49
19 52
EOF
and it should give the following results:
6.500315E+05 4.106162E+03 0.000000E+00

3.707419E+04 6.768262E+05 0.000000E+00
6.960534E+05 6.722946E+05 0.000000E+00
3.300000E+05 3.500000E+05 0.000000E+00

6.1.16 Equal Area Cylindrical
6.1.17 Chamberlin Trimetric
6.1. Projections 51
6.1.18 Collignon
6.1.19 Craster Parabolic (Putnins P4)

6.1.20 Denoyer Semi-Elliptical
6.1.21 Eckert I
√︀
𝑥 = 2 2/3𝜋𝜆(1 − |𝜑|/𝜋)
√︀
𝑦 = 2 2/3𝜋𝜑
6.1. Projections 53
6.1.22 Eckert II
6.1.23 Eckert III

6.1.24 Eckert IV
√
𝑥 = 𝜆(1 + 𝑐𝑜𝑠𝜑)/ 2 + 𝜋
√
𝑦 = 2𝜑/ 2 + 𝜋
6.1.25 Eckert V
6.1. Projections 55
6.1.26 Eckert VI
6.1.27 Equidistant Cylindrical (Plate Carrée)
The simplest of all projections. Standard parallels (0° when omitted) may be specified that determine latitude of true
scale (k=h=1).

Available forms Forward and inverse
Defined area Global, but best used near the equator
Alias eqc
Domain 2D

Usage
Because of the distortions introduced by this projection, it has little use in navigation or cadastral mapping and finds
its main use in thematic mapping. In particular, the plate carrée has become a standard for global raster datasets, such
as Celestia and NASA World Wind, because of the particularly simple relationship between the position of an image
pixel on the map and its corresponding geographic location on Earth.
The following table gives special cases of the cylindrical equidistant projection.
Projection Name (lat ts=) 𝜑0

Plain/Plane Chart 0°
Simple Cylindrical 0°
Plate Carrée 0°
Ronald Miller—minimum overall scale distortion 37°30′
E.Grafarend and A.Niermann 42°
Ronald Miller—minimum continental scale distortion 43°30′
Gall Isographic 45°
Ronald Miller Equirectangular 50°30′
E.Grafarend and A.Niermann minimum linear distortion 61°7′
Example using EPSG 32662 (WGS84 Plate Carrée):
$ echo 2 47 | proj +proj=eqc +lat_ts=0 +lat_0=0 +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84

˓→+datum=WGS84 +units=m +no_defs
222638.98 5232016.07
Example using Plate Carrée projection with true scale at latitude 30° and central meridian 90°W:
$ echo -88 30 | proj +proj=eqc +lat_ts=30 +lon_0=90w

192811.01 3339584.72
Parameters
+lon_0=<value>
Defaults to 0.0.
+lat_0=<value>
Defaults to 0.0.
+lat_ts=<value>
Defaults to 0.0.
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
6.1. Projections 57
+ellps=<value>
+R=<value>
The formulas describing the Equidistant Cylindrical projection are all taken from Snyder’s [Snyder1987].
𝜑𝑡𝑠 is the latitude of true scale, that mean the standard parallels where the scale of the projection is true. It can be set
with +lat_ts.
𝜑0 is the latitude of origin that match the center of the map. It can be set with +lat_0.
Forward projection
𝑥 = 𝜆 cos 𝜑𝑡𝑠
𝑦 = 𝜑 − 𝜑0
Inverse projection
𝜆 = 𝑥/𝑐𝑜𝑠𝜑𝑡𝑠
𝜑 = 𝑦 + 𝜑0
Further reading
1. Wikipedia
2. Wolfram Mathworld

6.1.28 Equidistant Conic
6.1.29 Euler
6.1. Projections 59
6.1.30 Extended Transverse Mercator
6.1.31 Fahey

6.1.32 Foucaut
6.1.33 Foucaut Sinusoidal
The y-axis is based upon a weighted mean of the cylindrical equal-area and the sinusoidal projections. Parameter
𝑛 = 𝑛 is the weighting factor where 0 <= 𝑛 <= 1.
𝑥 = 𝜆 cos 𝜑/(𝑛 + (1 − 𝑛) 𝑐𝑜𝑠𝜑)

𝑦 = 𝑛𝜑 + (1 − 𝑛) sin 𝜑
For the inverse, the Newton-Raphson method can be used to determine 𝜑 from the equation for 𝑦 above. As 𝑛 → 0
and 𝜑 → 𝜋/2, convergence is slow but for 𝑛 = 0, 𝜑 = sin1 𝑦
6.1. Projections 61
6.1.34 Gall (Gall Stereographic)
The Gall stereographic projection, presented by James Gall in 1855, is a cylindrical projection. It is neither equal-area
nor conformal but instead tries to balance the distortion inherent in any projection.

Available forms Forward and inverse, Spherical
Defined area Global
Alias gall
Domain 2D
Usage
The need for a world map which avoids some of the scale exaggeration of the Mercator projection has led to some
commonly used cylindrical modifications, as well as to other modifications which are not cylindrical. The earliest
common cylindrical example was developed by James Gall of Edinburgh about 1855 (Gall, 1885, p. 119-123). His
meridians are equally spaced, but the parallels are spaced at increasing intervals away from the Equator. The parallels
of latitude are actually projected onto a cylinder wrapped about the sphere, but cutting it at lats. 45° N. and S., the
point of perspective being a point on the Equator opposite the meridian being projected. It is used in several British
atlases, but seldom in the United States. The Gall projection is neither conformal nor equal-area, but has a blend of
various features. Unlike the Mercator, the Gall shows the poles as lines running across the top and bottom of the map.
Example using Gall Stereographical
$ echo 9 51 | proj +proj=gall +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84

˓→+units=m +no_defs
708432.90 5193386.36
Example using Gall Stereographical (Central meridian 90°W)

$ echo 9 51 | proj +proj=gall +lon_0=90w +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84

˓→+units=m +no_defs
7792761.91 5193386.36
Parameters
+lon_0=<value>
Defaults to 0.0.
+R=<value>
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
+ellps=<value>
The formulas describing the Gall Stereographical are all taken from Snyder’s [Snyder1993].
Spherical form
Forward projection
𝜆
𝑥= √
2
√
2
𝑦 = (1 + ) tan(𝜑/2)
2
Inverse projection
𝑦
𝜑 = 2 arctan( √ )
2
1+ 2
√
𝜆= 2𝑥
6.1. Projections 63
Further reading
1. Wikipedia
2. Cartographic Projection Procedures for the UNIX Environment-A User’s Manual
6.1.35 Geostationary Satellite View
The geos projection pictures how a geostationary satellite scans the earth at regular scanning angle intervals.
Defined area Global
Alias geos
Domain 2D
Usage
In order to project using the geos projection you can do the following:
proj +proj=geos +h=35785831.0
The required argument h is the viewing point (satellite position) height above the earth.
The projection coordinate relate to the scanning angle by the following simple relation:
scanning_angle (radians) = projection_coordinate / h

Note on sweep angle
The viewing instrument on-board geostationary satellites described by this projection have a two-axis gimbal viewing
geometry. This means that the different scanning positions are obtained by rotating the gimbal along a N/S axis (or y)
and a E/W axis (or x).
In the image above, the outer-gimbal axis, or sweep-angle axis, is the N/S axis (y) while the inner-gimbal axis, or
fixed-angle axis, is the E/W axis (x).
This example represents the scanning geometry of the Meteosat series satellite. However, the GOES satellite series
use the opposite scanning geometry, with the E/W axis (x) as the sweep-angle axis, and the N/S (y) as the fixed-angle
axis.
The sweep argument is used to tell PROJ which on which axis the outer-gimbal is rotating. The possible values are
x or y, y being the default. Thus, the scanning geometry of the Meteosat series satellite should take sweep as x, and
GOES should take sweep as y.
Parameters
Required
+h=<value>
Height of the view point above the Earth and must be in the same units as the radius of the sphere or semimajor
axis of the ellipsoid.
6.1. Projections 65
Optional
+sweep=<axis>
Sweep angle axis of the viewing instrument. Valid options are “x” and “y”.
Defaults to “y”.
+lon_0=<value>
Defaults to 0.0.
+R=<value>
+ellps=<value>
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
6.1.36 Ginsburg VIII (TsNIIGAiK)

6.1.37 General Sinusoidal Series
6.1.38 Gnomonic
6.1. Projections 67
6.1.39 Goode Homolosine
6.1.40 Mod. Stererographics of 48 U.S.

6.1.41 Mod. Stererographics of 50 U.S.
6.1.42 Hammer & Eckert-Greifendorff
6.1. Projections 69
6.1.43 Hatano Asymmetrical Equal Area
Classification Pseudocylindrical Projection

Defined area Global
Alias hatano
Domain 2D
Parameters
+lon_0=<value>
Defaults to 0.0.
+R=<value>
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.

Mathematical Definition
Forward
𝑥 = 0.85𝜆 cos 𝜃
𝑦 = 𝐶𝑦 sin 𝜃
𝑃 (𝜃) = 2𝜃 + sin 2𝜃 − 𝐶𝑝 sin 𝜑
𝑃 ′ (𝜃) = 2(1 + cos 2𝜃)
𝜃0 = 2𝜑
Condition 𝐶𝑦 𝐶𝑝
For 𝜑 > 0 1.75859 2.67595
For 𝜑 < 0 1.93052 2.43763
For 𝜑 = 0, 𝑦 ← 0, and 𝑥 ← 0.85𝜆.
Further reading
1. Compare Map Projections

2. Mathworks
6.1.44 HEALPix
Defined area Global
Alias healpix
Domain 2D
6.1. Projections 71
The HEALPix projection is area preserving and can be used with a spherical and ellipsoidal model. It was initially
developed for mapping cosmic background microwave radiation. The image below is the graphical representation
of the mapping and consists of eight isomorphic triangular interrupted map graticules. The north and south contains
four in which straight meridians converge polewards to a point and unequally spaced horizontal parallels. HEALPix
provides a mapping in which points of equal latitude and equally spaced longitude are mapped to points of equal
latitude and equally spaced longitude with the module of the polar interruptions.
Usage
To run a forward HEALPix projection on a unit sphere model, use the following command:
proj +proj=healpix +lon_0=0 +a=1 -E <<EOF

0 0
EOF
# output
0 0 0.00 0.00
Parameters
+lon_0=<value>
Defaults to 0.0.
+x_0=<value>
False easting.
Defaults to 0.0.

+y_0=<value>
False northing.
Defaults to 0.0.
+ellps=<value>
+R=<value>
Further reading
1. NASA
2. Wikipedia
6.1.45 rHEALPix
Defined area Global
Alias rhealpix
Domain 2D
6.1. Projections 73
rHEALPix is a projection based on the HEALPix projection. The implementation of rHEALPix uses the HEALPix
projection. The rHEALPix combines the peaks of the HEALPix into a square. The square’s position can be translated
and rotated across the x-axis which is a novel approach for the rHEALPix projection. The initial intention of using
rHEALPix in the Spatial Computation Engine Science Collaboration Environment (SCENZGrid).
Usage
To run a rHEALPix projection on a WGS84 ellipsoidal model, use the following command:
proj +proj=rhealpix -f '%.2f' +ellps=WGS84 +south_square=0 +north_square=2 -E << EOF

> 55 12
> EOF
55 12 6115727.86 1553840.13
Parameters
+north_square
Position of the north polar square. Valid inputs are 0–3.
Defaults to 0.0.

+south_square
Position of the south polar square. Valid inputs are 0–3.
Defaults to 0.0.
+lon_0=<value>
Defaults to 0.0.
+ellps=<value>
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
Further reading
1. NASA
2. Wikipedia
6.1.46 Interrupted Goode Homolosine
6.1. Projections 75
6.1.47 International Map of the World Polyconic
6.1.48 Icosahedral Snyder Equal Area

6.1.49 Kavraisky V
6.1.50 Kavraisky VII
6.1. Projections 77
6.1.51 Krovak
6.1.52 Laborde

6.1.53 Lambert Azimuthal Equal Area
6.1.54 Lagrange
6.1. Projections 79
6.1.55 Larrivee
6.1.56 Laskowski

6.1.57 Lambert Conformal Conic
6.1.58 Lambert Conformal Conic Alternative
6.1. Projections 81
6.1.59 Lambert Equal Area Conic
6.1.60 Lee Oblated Stereographic

6.1.61 Loximuthal
6.1.62 Space oblique for LANDSAT
6.1. Projections 83
6.1.63 McBryde-Thomas Flat-Polar Sine (No. 1)
6.1.64 McBryde-Thomas Flat-Pole Sine (No. 2)

6.1.65 McBride-Thomas Flat-Polar Parabolic
6.1.66 McBryde-Thomas Flat-Polar Quartic
6.1. Projections 85
6.1.67 McBryde-Thomas Flat-Polar Sinusoidal
6.1.68 Mercator
The Mercator projection is a cylindrical map projection that origins from the 15th century. It is widely recognized as
the first regularly used map projection. The projection is conformal which makes it suitable for navigational purposes.

Alias merc
Domain 2D

Usage
Applications should be limited to equatorial regions, but is frequently used for navigational charts with latitude of true
scale (+lat_ts) specified within or near chart’s boundaries. Often inappropriately used for world maps since the
regions near the poles cannot be shown [Evenden1995].
Example using latitude of true scale:
$ echo 56.35 12.32 | proj +proj=merc +lat_ts=56.5

3470306.37 759599.90
Example using scaling factor:
echo 56.35 12.32 | proj +proj=merc +k_0=2

12545706.61 2746073.80
Note that +lat_ts and +k_0 are mutually exclusive. If used together, +lat_ts takes precedence over +k_0.
Parameters
+lat_ts=<value>
Defaults to 0.0.
+k_0=<value>
Defaults to 1.0.
+lon_0=<value>
Defaults to 0.0.
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
+ellps=<value>
+R=<value>
6.1. Projections 87
The formulas describing the Mercator projection are all taken from G. Evenden’s libproj manuals [Evenden2005].
Spherical form
For the spherical form of the projection we introduce the scaling factor:
𝑘0 = cos 𝜑𝑡𝑠
Forward projection
𝑥 = 𝑘0 𝜆
[︂ (︂ )︂]︂
𝜋 𝜑
𝑦 = 𝑘0 ln tan +
4 2
Inverse projection
𝑥
𝜆=
𝑘0
𝜋 [︁ ]︁
𝜑= − 2 arctan 𝑒−𝑦/𝑘0
2
Elliptical form
For the elliptical form of the projection we introduce the scaling factor:
𝑘0 = 𝑚 (𝜑𝑡 𝑠)
where 𝑚 (𝜑) is the parallel radius at latitude 𝜑.

We also use the Isometric Latitude kernel function 𝑡().
Note: m() and t() should be described properly on a separate page about the theory of projections on the ellipsoid.
Forward projection
𝑥 = 𝑘0 𝜆
𝑦 = 𝑘0 ln 𝑡 (𝜑)

Inverse projection
𝑥
𝜆=
𝑘0
[︁ ]︁
𝜑 = 𝑡−1 𝑒−𝑦/𝑘0
Further reading
1. Wikipedia
2. Wolfram Mathworld
6.1.69 Miller Oblated Stereographic
6.1.70 Miller Cylindrical
The Miller cylindrical projection is a modified Mercator projection, proposed by Osborn Maitland Miller in 1942. The
latitude is scaled by a factor of 54 , projected according to Mercator, and then the result is multiplied by 54 to retain scale
along the equator.
Classification Neither conformal nor equal area cylindrical

Available forms Forward and inverse spherical
Alias mill
Domain 2D
6.1. Projections 89
Usage
The Miller Cylindrical projection is used for world maps and in several atlases, including the National Atlas of the
United States (USGS, 1970, p. 330-331) [Snyder1987].
Example using Central meridian 90°W:
$ echo -100 35 | proj +proj=mill +lon_0=90w
-1113194.91 4061217.24
Parameters
+lon_0=<value>
Defaults to 0.0.
+R=<value>
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
The formulas describing the Miller projection are all taken from Snyder’s manuals [Snyder1987].

Forward projection
𝑥=𝜆
[︁ (︁ 𝜋 )︁]︁
𝑦 = 1.25 * ln tan + 0.4 * 𝜑
4
Inverse projection
𝜆=𝑥
]︀ 𝜋
𝜑 = 2.5 * (arctan 𝑒0.8*𝑦 − )
[︀
4
Further reading
1. Wikipedia
6.1.71 Mollweide
6.1. Projections 91
6.1.72 Murdoch I
6.1.73 Murdoch II

6.1.74 Murdoch III
6.1.75 Natural Earth
Classification Pseudo cylindrical

Defined area Global
Alias natearth
Domain 2D
The Natural Earth projection is intended for making world maps. A distinguishing trait is its slightly rounded corners
fashioned to emulate the spherical shape of Earth. The meridians (except for the central meridian) bend acutely inward
6.1. Projections 93
as they approach the pole lines, giving the projection a hint of three-dimensionality. This bending also suggests that
the meridians converge at the poles instead of truncating at the top and bottom edges. The distortion characteristics of
the Natural Earth projection compare favorably to other world map projections.
Usage
The Natural Earth projection has no special options so usage is simple. Here is an example of an inverse projection on
a sphere with a radius of 7500 m:
$ echo 3500 -8000 | proj -I +proj=natearth +a=7500

37d54'6.091"E 61d23'4.582"S
Parameters
+lon_0=<value>
Defaults to 0.0.
+R=<value>
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
Further reading
1. Wikipedia

6.1.76 Nell
6.1.77 Nell-Hammer
6.1. Projections 95
6.1.78 Nicolosi Globular
6.1.79 Near-sided perspective
The near-sided perspective projection simulates a view from a height ℎ similar to how a satellite in orbit would see it.
Classification Azimuthal. Neither conformal nor equal area.

Available forms Forward and inverse spherical projection
Defined area Global, although for one hemisphere at a time.
Alias nsper
Domain 2D

Parameters
Required
+h=<value>
Optional
+lon_0=<value>
Defaults to 0.0.
+R=<value>
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
6.1.80 New Zealand Map Grid
6.1. Projections 97
6.1.81 General Oblique Transformation
6.1.82 Oblique Cylindrical Equal Area

6.1.83 Oblated Equal Area
6.1.84 Oblique Mercator
6.1. Projections 99
6.1.85 Ortelius Oval
6.1.86 Orthographic
The orthographic projection is a perspective azimuthal projection centered around a given latitude and longitude.
Defined area Global, although only one hemisphere can be seen at a time
Alias ortho
Domain 2D

Parameters
+lon_0=<value>
Defaults to 0.0.
+lat_0=<value>
Defaults to 0.0.
+R=<value>
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
6.1.87 Perspective Conic
6.1. Projections 101

6.1.88 Polyconic (American)
6.1.89 Putnins P1

6.1.90 Putnins P2
6.1.91 Putnins P3

6.1.92 Putnins P3’

6.1.94 Putnins P5

6.1.96 Putnins P6

6.1.98 Quartic Authalic
6.1.99 Quadrilateralized Spherical Cube
Available forms Forward and inverse, elliptical projection
Defined area Global
Alias qsc
Domain 2D
The purpose of the Quadrilateralized Spherical Cube (QSC) projection is to project a sphere surface onto the six sides
of a cube:

For this purpose, other alternatives can be used, notably Gnomonic or HEALPix. However, QSC projection has the
following favorable properties:
It is an equal-area projection, and at the same time introduces only limited angular distortions. It treats all cube sides
equally, i.e. it does not use different projections for polar areas and equatorial areas. These properties make QSC
projection a good choice for planetary-scale terrain rendering. Map data can be organized in quadtree structures for
each cube side. See [LambersKolb2012] for an example.
The QSC projection was introduced by [ONeilLaubscher1976], building on previous work by [ChanONeil1975]. For
clarity: The earlier QSC variant described in [ChanONeil1975] became known as the COBE QSC since it was used
by the NASA Cosmic Background Explorer (COBE) project; it is an approximately equal-area projection and is not
the same as the QSC projection.
See also [CalabrettaGreisen2002] Sec. 5.6.2 and 5.6.3 for a description of both and some analysis.
In this implementation, the QSC projection projects onto one side of a circumscribed cube. The cube side is selected
by choosing one of the following six projection centers:
+lat_0=0 +lon_0=0 front cube side

+lat_0=0 +lon_0=90 right cube side
+lat_0=0 +lon_0=180 back cube side
+lat_0=0 +lon_0=-90 left cube side
+lat_0=90 top cube side
+lat_0=-90 bottom cube side
Furthermore, this implementation allows the projection to be applied to ellipsoids. A preceding shift to a sphere is
performed automatically; see [LambersKolb2012] for details.

Usage
The following example uses QSC projection via GDAL to create the six cube side maps from a world map for the
WGS84 ellipsoid:
gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=0" \

-wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \
worldmap.tiff frontside.tiff

worldmap.tiff rightside.tiff

worldmap.tiff backside.tiff
gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=-90" \

worldmap.tiff leftside.tiff

worldmap.tiff topside.tiff
gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=-90 +lon_0=0" \

worldmap.tiff bottomside.tiff
Explanation:
• QSC projection is selected with +wktext +proj=qsc.
• The WGS84 ellipsoid is specified with +ellps=WGS84.
• The cube side is selected with +lat_0=... +lon_0=....
• The -wo options are necessary for GDAL to avoid holes in the output maps.
• The -te option limits the extends of the output map to the major axis diameter (from -radius to +radius in both
x and y direction). These are the dimensions of one side of the circumscribing cube.
The resulting images can be laid out in a grid like below.

Parameters
+lon_0=<value>
Defaults to 0.0.
+lat_0=<value>
Defaults to 0.0.
+ellps=<value>
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.

Further reading
1. Wikipedia
2. NASA
6.1.100 Robinson
6.1.101 Roussilhe Stereographic

6.1.102 Rectangular Polyconic
6.1.103 Sinusoidal (Sanson-Flamsteed)
MacBryde and Thomas developed generalized formulas for sever of the pseudocylindricals with sinusoidal meridians:
𝑥 = 𝐶𝜆(𝑚 + 𝑐𝑜𝑠𝜃)/(𝑚 + 1)
𝑦 = 𝐶𝜃
√︀
𝐶 = (𝑚 + 1)/𝑛

6.1.104 Swiss. Obl. Mercator
6.1.105 Stereographic

6.1.106 Oblique Stereographic Alternative
6.1.107 Gauss-Schreiber Transverse Mercator (aka Gauss-Laborde Reunion)

6.1.108 Transverse Central Cylindrical
6.1.109 Transverse Cylindrical Equal Area

6.1.110 Tissot
6.1.111 Transverse Mercator
The transverse Mercator projection in its various forms is the most widely used projected coordinate system for world
topographical and offshore mapping.

Available forms Forward and inverse, Spherical and Elliptical
Defined area Global, but reasonably accurate only within 15 degrees of the central meridian
Alias tmerc
Domain 2D

Usage
Prior to the development of the Universal Transverse Mercator coordinate system, several European nations demon-
strated the utility of grid-based conformal maps by mapping their territory during the interwar period. Calculating
the distance between two points on these maps could be performed more easily in the field (using the Pythagorean
theorem) than was possible using the trigonometric formulas required under the graticule-based system of latitude and
longitude. In the post-war years, these concepts were extended into the Universal Transverse Mercator/Universal Polar
Stereographic (UTM/UPS) coordinate system, which is a global (or universal) system of grid-based maps.
The following table gives special cases of the Transverse Mercator projection.
Projection Name Areas Central meridian Zone width Scale

Factor
Transverse Mercator World wide Various less than 6° Vari-
ous
Transverse Mercator Southern Africa 2° intervals E of 2° 1.000
south oriented 11°E
UTM North hemi- World wide equator to 84°N 6° intervals E & W Always 6° 0.9996
sphere of 3° E & W
UTM South hemi- World wide north of 80°S to 6° intervals E & W Always 6° 0.9996
sphere equator of 3° E & W
Gauss-Kruger Former USSR, Yugoslavia, Ger- Various, according Usually less than 6°, 1.0000
many, S. America, China to area often less than 4°
Gauss Boaga Italy Various, according 6° 0.9996
to area
Example using Gauss-Kruger on Germany area (aka EPSG:31467)
$ echo 9 51 | proj +proj=tmerc +lat_0=0 +lon_0=9 +k=1 +x_0=3500000 +y_0=0

˓→+ellps=bessel +datum=potsdam +units=m +no_defs
3500000.00 5651505.56
Example using Gauss Boaga on Italy area (EPSG:3004)
$ echo 15 42 | proj +proj=tmerc +lat_0=0 +lon_0=15 +k=0.9996 +x_0=2520000 +y_0=0

˓→+ellps=intl +units=m +no_defs
2520000.00 4649858.60
Parameters
+lon_0=<value>
Defaults to 0.0.
+lat_0=<value>
Defaults to 0.0.
+ellps=<value>

+R=<value>
+k_0=<value>
Defaults to 1.0.
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
The formulas describing the Transverse Mercator are all taken from Evenden’s [Evenden2005].
𝜑0 is the latitude of origin that match the center of the map. It can be set with +lat_0.
𝑘0 is the scale factor at the natural origin (on the central meridian). It can be set with +k_0.
𝑀 (𝜑) is the meridional distance.
Spherical form
Forward projection
𝐵 = cos 𝜑 sin 𝜆
𝑘0 1+𝐵
𝑥= ln( )
2 1−𝐵
tan(𝜑)
𝑦 = 𝑘0 (arctan( ) − 𝜑0 )
cos 𝜆
Inverse projection
𝑦
𝐷= + 𝜑0
𝑘0
𝑥
𝑥′ =
𝑘0
sin 𝐷
𝜑 = arcsin( )
cosh 𝑥′
sinh 𝑥′
𝜆 = arctan( )
cos 𝐷

Elliptical form
Forward projection
𝑘0
𝑁=
(1 − 𝑒2 sin2 𝜑)1/2
𝑘0 (1 − 𝑒2 )
𝑅=
(1 − 𝑒2 sin2 𝜑)3/2
𝑡 = tan(𝜑)
𝑒2
𝜂= 𝑐𝑜𝑠2 𝜑
1 − 𝑒2
𝑥 = 𝑘0 𝜆 cos 𝜑
𝑘0 𝜆3 cos3 𝜑
+ (1 − 𝑡2 + 𝜂 2 )
3!
+ (5 − 18𝑡2 + 𝑡4 + 14𝜂 2 − 58𝑡2 𝜂 2 )
5!
+ (61 − 479𝑡2 + 179𝑡4 − 𝑡6 )
7!
𝑦 = 𝑀 (𝜑)
𝑘0 𝜆2 sin(𝜑) cos 𝜑
+
2!
𝑘0 𝜆4 sin(𝜑) cos3 𝜑
+ (5 − 𝑡2 + 9𝜂 2 + 4𝜂 4 )
4!
+ (61 − 58𝑡2 + 𝑡4 + 270𝜂 2 − 330𝑡2 𝜂 2 )
6!
+ (1385 − 3111𝑡2 + 543𝑡4 − 𝑡6 )
8!
Inverse projection
𝜑1 = 𝑀 − 1(𝑦)
𝑘0
𝑁1 =
1 − 𝑒2 sin2 𝜑1 )1/2
𝑘0 (1 − 𝑒2 )
𝑅1 =
(1 − 𝑒2 sin2 𝜑1 )3/2
𝑡1 = tan(𝜑1 )
𝑒2
𝜂1 = 𝑐𝑜𝑠2 𝜑1
1 − 𝑒2

𝜑 = 𝜑1
𝑡 1 𝑥2
−
2!𝑅1 𝑁1
𝑡 1 𝑥4
+ (5 + 3𝑡21 + 𝜂12 − 4𝜂14 − 9𝜂12 𝑡21 )
4!𝑅1 𝑁13
𝑡1 𝑥6
− (61 + 90𝑡21 + 46𝜂12 + 45𝑡41 − 252𝑡21 𝜂12 )
6!𝑅1 𝑁15
𝑡 1 𝑥8
+ (1385 + 3633𝑡21 + 4095𝑡41 + 1575𝑡61 )
8!𝑅1 𝑁17
𝑥
𝜆=
cos 𝜑𝑁1
𝑥3
− (1 + 2𝑡21 + 𝜂12 )
3! cos 𝜑𝑁13
𝑥5
+ (5 + 6𝜂12 + 28𝑡21 − 3𝜂12 + 8𝑡21 𝜂12 )
5! cos 𝜑𝑁15
𝑥7
− (61 + 662𝑡21 + 1320𝑡41 + 720𝑡61 )
7! cos 𝜑𝑁17
Further reading
1. Wikipedia
2. EPSG, POSC literature pertaining to Coordinate Conversions and Transformations including Formulas
6.1.112 Two Point Equidistant

6.1.113 Tilted perspective
Defined area Global
Alias tpers
Domain 2D
Tilted Perspective is similar to Near-sided perspective (nsper) in that it simulates a perspective view from a height.
Where nsper projects onto a plane tangent to the surface, Tilted Perspective orients the plane towards the direction of
the view. Thus, extra parameters specifying azimuth and tilt are required beyond nsper‘’s h. As with nsper, lat_0
& lon_0 are also required for satellite position.
Parameters
Required
+h=<value>
Optional
+azi=<value>
Bearing in degrees away from north.
Defaults to 0.0.
+tilt=<value>
Angle in degrees away from nadir.
Defaults to 0.0.

+lon_0=<value>
Defaults to 0.0.
+lat_0=<value>
Defaults to 0.0.
+R=<value>
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
6.1.114 Universal Polar Stereographic

6.1.115 Urmaev V
6.1.116 Urmaev Flat-Polar Sinusoidal

6.1.117 Universal Transverse Mercator (UTM)
6.1.118 van der Grinten (I)

6.1.119 van der Grinten II
6.1.120 van der Grinten III

6.1.121 van der Grinten IV
6.1.122 Vitkovsky I

6.1.123 Wagner I (Kavraisky VI)
6.1.124 Wagner II
𝑥 = 0.92483𝜆 cos 𝜃
𝑦 = 1.38725𝜃
sin 𝜃 = 0.88022 sin(0.8855𝜑)

6.1.125 Wagner III
𝑥 = [cos 𝜑𝑡𝑠 / cos(2𝜑𝑡𝑠 /3)]𝜆 cos(2𝜑/3)

𝑦=𝜑
6.1.126 Wagner IV

6.1.127 Wagner V
6.1.128 Wagner VI

6.1.129 Wagner VII
6.1.130 Web Mercator / Pseudo Mercator

The Web Mercator / Pseudo Mercator projection is a cylindrical map projection. This is a variant of the regular
Mercator projection, except that the computation is done on a sphere, using the semi-major axis of the ellipsoid.
From Wikipedia:
This projection is widely used by the Web Mercator, Google Web Mercator, Spherical Mercator, WGS 84
Web Mercator[1] or WGS 84/Pseudo-Mercator is a variant of the Mercator projection and is the de facto
standard for Web mapping applications. [. . . ] It is used by virtually all major online map providers [. . . ]
Its official EPSG identifier is EPSG:3857, although others have been used historically.
Classification Cylindrical (non conformant if used with ellipsoid)

Alias webmerc
Domain 2D
Usage
Example:
$ echo 2 49 | proj +proj=webmerc +datum=WGS84

222638.98 6274861.39
Parameters

+R=<value>
+x_0=<value>
False easting.
Defaults to 0.0.
+y_0=<value>
False northing.
Defaults to 0.0.
The formulas describing the Mercator projection are all taken from G. Evenden’s libproj manuals [Evenden2005].
Forward projection
𝑥=𝜆
[︂ (︂ )︂]︂
𝜋 𝜑
𝑦 = ln tan +
4 2
Inverse projection
𝜆=𝑥
𝜋
− 2 arctan 𝑒−𝑦
[︀ ]︀
𝜑=
2
Further reading
1. Wikipedia

6.1.131 Werenskiold I
6.1.132 Winkel I

6.1.133 Winkel II
6.1.134 Winkel Tripel
6.2 Conversions
Conversions are coordinate operations in which both coordinate reference systems are based on the same datum. In
PROJ projections are differentiated from conversions.
6.2.1 Axis swap
6.2. Conversions 133

Change the order and sign of 2,3 or 4 axes.
Alias axisswap
Domain 2D, 3D or 4D
Input type Any
Output type Any
Each of the possible four axes are numbered with 1–4, such that the first input axis is 1, the second is 2 and so on. The
output ordering is controlled by a list of the input axes re-ordered to the new mapping.
Usage
Reversing the order of the axes:
+proj=axisswap +order=4,3,2,1
Swapping the first two axes (x and y):
+proj=axisswap +order=2,1,3,4
The direction, or sign, of an axis can be changed by adding a minus in front of the axis-number:
+proj=axisswap +order=1,-2,3,4
It is only necessary to specify the axes that are affected by the swap operation:
+proj=axisswap +order=2,1
Parameters
+order=<list>
Ordered comma-separated list of axis, e.g. +order=2,1,3,4. Adding a minus in front of an axis number results
in a change of direction for that axis, e.g. southward instead of northward.
Required.
6.2.2 Cartesian to geodetic conversion

Convert geodetic coordinates to cartesian coordinates.
Alias cart
Domain 3D
Input type Cartesian coordinates
Output type Cartesian coordinates
Parameters
+ellps=<value>

6.2.3 Lat/long (Geodetic alias)
Passes geodetic coordinates through unchanged.
Aliases latlon, latlong, lonlat, longlat

Domain 2D
Output type Geodetic coordinates
Note: Can not be used with the proj application.
Parameters
No parameters will affect the output of the operation if used on it’s own. However, the parameters below can be used
in a declarative manner when used with cs2cs or in a transformation pipeline .
+ellps=<value>
+datum=<value>
Declare the datum used with the coordinates. See cs2cs -l for a list of available datums.
+towgs84=<list>
A list of three or seven Helmert parameters that maps the input coordinates to the WGS84 datum.
6.2.4 Unit conversion

Convert between various distance and time units.
Alias unitconvert
Domain 2D, 3D or 4D
Input type Any
Output type Any
There are many examples of coordinate reference systems that are expressed in other units than the meter. There are
also many cases where temporal data has to be translated to different units. The unitconvert operation takes care of
that.
Many North American systems are defined with coordinates in feet. For example in Vermont:
+proj=pipeline
+step +proj=tmerc +lat_0=42.5 +lon_0=-72.5 +k=0.999964286 +x_0=500000.00001016 +y_0=0
+step +proj=unitconvert +xy_in=m +xy_out=us-ft
Often when working with GNSS data the timestamps are presented in GPS-weeks, but when the data transformed with
the helmert operation timestamps are expected to be in units of decimalyears. This can be fixed with unitconvert:
6.2. Conversions 135

+proj=pipeline
+step +proj=unitconvert +t_in=gpsweek +t_out=decimalyear
+step +proj=helmert +epoch=2000.0 +t_obs=2017.5 ...
Parameters
+xy_in=<unit>
Horizontal input units. See Distance units for a list of available units.
+xy_out=<unit>
Horizontal output units. See Distance units for a list of available units.
+z_in=<unit>
Vertical output units. See Distance units for a list of available units.
+z_out=<unit>
Vertical output units. See Distance units for a list of available units.
+t_in=<unit>
Temporal input units. See Time units for a list of available units.
+t_out=<unit>
Temporal output units. See Time units for a list of available units.
Distance units
In the table below all distance units supported by PROJ is listed. The same list can also be produced on the command
line with proj or cs2cs, by adding the -lu flag when calling the utility.
Label Name
km Kilometer
m Meter
dm Decimeter
cm Centimeter
mm Millimeter
kmi International Nautical Mile
in International Inch
ft International Foot
yd International Yard
mi International Statute Mile
fath International Fathom
ch International Chain
link International Link
us-in U.S. Surveyor’s Inch
us-ft U.S. Surveyor’s Foot
us-yd U.S. Surveyor’s Yard
us-ch U.S. Surveyor’s Chain
us-mi U.S. Surveyor’s Statute Mile
ind-yd Indian Yard
ind-ft Indian Foot
ind-ch Indian Chain

Time units
In the table below all time units supported by PROJ is listed.
label Name
mjd Modified Julian date
decimalyear Decimal year
gps_week GPS Week
yyyymmdd Date in yyyymmdd format
6.3 Transformations
Transformations coordinate operation in which the two coordinate reference systems are based on different datums.
6.3.1 Kinematic datum shifting utilizing a deformation model

Perform datum shifts means of a deformation/velocity model.
Input type Cartesian coordinates (spatial), decimalyears (temporal).

Output type Cartesian coordinates (spatial), decimalyears (temporal).
Domain 4D
Output type Geodetic coordinates
The deformation operation is used to adjust coordinates for intraplate deformations. Usually the transformation param-
eters for regional plate-fixed reference frames such as the ETRS89 does not take intraplate deformation into account.
It is assumed that tectonic plate of the region is rigid. Often times this is true, but near the plate boundary and in
areas with post-glacial uplift the assumption breaks. Intraplate deformations can be modelled and then applied to the
coordinates so that they represent the physical world better. In PROJ this is done with the deformation operation.
The horizontal grid is stored in CTable2 format and the vertical grid is stored in the GTX format. Both grids are ex-
pected to contain grid-values in units of mm/year. Details about the formats can be found in the GDAL documentation.
GDAL both reads and writes both file formats. Using GDAL for construction of new grids is recommended.
Example
In [Häkli2016] coordinate transformation including a deformation model is described. The paper describes how
coordinates from the global ITRFxx frames are transformed to the local Nordic realisations of ETRS89. Scandinavia
is an area with significant post-glacial rebound. The deformations from the post-glacial uplift is not accounted for in
the official ETRS89 transformations so in order to get accurate transformations in the Nordic countries it is necessary
to apply the deformation model. The transformation from ITRF2008 to the Danish realisation of ETRS89 is in PROJ
described as:
proj = pipeline ellps = GRS80

# ITRF2008@t_obs -> ITRF2000@t_obs
step init = ITRF2008:ITRF2000
# ITRF2000@t_obs -> ETRF2000@t_obs
step proj=helmert t_epoch = 2000.0 transpose
6.3. Transformations 137


x = 0.054 rx = 0.000891 drx = 8.1e-05
y = 0.051 ry = 0.00539 dry = 0.00049
z = -0.048 rz = -0.008712 drz = -0.000792
# ETRF2000@t_obs -> [email protected]
step proj = deformation t_epoch = 2000.0
xy_grids = ./nkgrf03vel_realigned_xy.ct2
z_grids = ./nkgrf03vel_realigned_z.gtx
# [email protected] -> [email protected]
step proj=helmert transpose s = -0.009420e
x = 0.03863 rx = 0.00617753
y = 0.147 ry = 5.064e-05
z = 0.02776 rz = 4.729e-05
# [email protected] -> [email protected]
step proj = deformation t_epoch = 1994.704 t_obs = 2000.0
From this we can see that the transformation from ITRF2008 to the Danish realisation of ETRS89 is a combination of
Helmert transformations and adjustments with a deformation model. The first use of the deformation operation is:
proj = deformation t_epoch = 2000.0

Here we set the central epoch of the transformation, 2000.0. The observation epoch is expected as part of the input
coordinate tuple. The deformation model is described by two grids, specified with +xy_grids and +z_grids. The
first is the horizontal part of the model and the second is the vertical component.
Parameters
Required
+xy_grids=<list>
Comma-separated list of grids to load. If a grid is prefixed by an @ the grid is consideres optional and PROJ
will the not complain if the grid is not available.
Grids for the horizontla component of a deformation model is expected to be in CTable2 format.
+z_grids=<list>
Comma-separated list of grids to load. If a grid is prefixed by an @ the grid is consideres optional and PROJ
Grids for the vertical component of a deformation model is expected to be in either GTX format.
+t_epoch=<value>
Central epoch of transformation given in decimalyears.
Optional
+t_obs=<value>
Observation time of coordinate(s) given in decimalyears. If not specified, the observation time from the temporal
component of 4D input points is used.

Mathematical description
Mathematically speaking, application of a deformation model is simple. The deformation model is represented as a
grid of velocities in three dimensions. Coordinate corrections are applied in cartesian space. For a given coordinate,
(𝑋, 𝑌, 𝑍), velocities (𝑉𝑋 , 𝑉𝑌 , 𝑉𝑍 ) can be interpolated from the gridded model. The time span between 𝑡𝑐 and 𝑡𝑜𝑏𝑠
determine the magnitude of the coordinate correcton as seen in eq. (6.1) below.
⎛ ⎞ ⎛ ⎞ ⎛ ⎞
𝑋 𝑋 𝑉𝑋
⎝ 𝑌 ⎠ = ⎝ 𝑌 ⎠ + (𝑡𝑐 − 𝑡𝑜𝑏𝑠 ) ⎝ 𝑉𝑌 ⎠ (6.1)
𝑍 𝐵 𝑍 𝐴 𝑉𝑍
Corrections are done in cartesian space.
Coordinates of the gridded model are in ENU (east, north, up) space because it would otherwise require an enormous
3 dimensional grid to handle the corrections in cartesian space. Keeping the correction in lat/long space reduces the
complexity of the grid significantly. Consequently though, the input coordinates needs to be converted to lat/long
space when searching for corrections in the grid. This is done with the cart operation. The converted grid corrections
can then be applied to the input coordinates in cartesian space. The conversion from ENU space to cartesian space is
done in the following way:
⎛ ⎞ ⎛ ⎞
𝑋 − sin 𝜑 cos 𝜆𝑁 − sin 𝜆𝐸 + cos 𝜑 cos 𝜆𝑈
⎝ 𝑌 ⎠ = ⎝ − sin 𝜑 sin 𝜆𝑁 + sin 𝜆𝐸 + cos 𝜑 sin 𝜆𝑈 ⎠ (6.1)
𝑍 cos 𝜑𝑁 + sin 𝜑𝑈
where 𝜑 and 𝜆 are the latitude and longitude of the coordinate that is searched for in the grid. (𝐸, 𝑁, 𝑈 ) are the grid
values in ENU-space and (𝑋, 𝑌, 𝑍) are the corrections converted to cartesian space.
6.3.2 Helmert transform

The Helmert transformation changes coordinates from one reference frame to anoether by means of 3-, 4-and 7-
parameter shifts, or one of their 6-, 8- and 14-parameter kinematic counterparts.
Alias helmert
Domain 2D, 3D and 4D
Input type Cartesian coordinates (spatial), decimalyears (temporal).
Output type Cartesian coordinates (spatial), decimalyears (temporal).
Input type Cartesian coordinates
Output type Cartesian coordinates
The Helmert transform, in all it’s various incarnations, is used to perform reference frame shifts. The transformation
operates in cartesian space. It can be used to transform planar coordinates from one datum to another, transform 3D
cartesian coordinates from one static reference frame to another or it can be used to do fully kinematic transformations
from global reference frames to local static frames.
All of the parameters described in the table above are marked as optional. This is true as long as at least one parameter
is defined in the setup of the transformation. The behaviour of the transformation depends on which parameters are
used in the setup. For instance, if a rate of change parameter is specified a kinematic version of the transformation is
used.
The kinematic transformations require an observation time of the coordinate, as well as a central epoch for the trans-
formation. The latter is usually documented alongside the rest of the transformation parameters for a given transfor-
mation. The central epoch is controlled with the parameter t_epoch. The observation time can either by stated as
part of the coordinate when using PROJ’s 4D-functionality or it can be controlled in the transformation setup by the
parameter t_obs. When t_obs is specified, all transformed coordinates are treated as if they have the same observation
time.

Examples
Transforming coordinates from NAD72 to NAD83 using the 4 parameter 2D Helmert:
proj=helmert ellps=GRS80 x=-9597.3572 y=.6112

s=0.304794780637 theta=-1.244048
Simplified transformations from ITRF2008/IGS08 to ETRS89 using 7 parameters:
proj=helmert ellps=GRS80 x=0.67678 y=0.65495 z=-0.52827

rx=-0.022742 ry=0.012667 rz=0.022704 s=-0.01070
Transformation from [email protected] to [email protected] using 15 parameters:
proj=helmert ellps=GRS80
x=0.0127 y=0.0065 z=-0.0209 s=0.00195
dx=-0.0029 dy=-0.0002 dz=-0.0006 ds=0.00001
rx=-0.00039 ry=0.00080 rz=-0.00114
drx=-0.00011 dry=-0.00019 drz=0.00007
t_epoch=1988.0 t_obs=2017.0 transpose
Parameters
Note: All parameters are optional but at least one should be used, otherwise the operation will return the coordinates
unchanged.
+x=<value>
Translation of the x-axis given in meters.
+y=<value>
Translation of the x-axis given in meters.
+z=<value>
Translation of the z-axis given in meters.
+s=<value>
Scale factor given in ppm.
+rx=<value>
X-axis rotation in the 3D Helmert given arc seconds.
+ry=<value>
Y-axis rotation in the 3D Helmert given in arc seconds.
+rz=<value>
Z-axis rotation in the 3D Helmert given in arc seconds.
+theta=<value>
Rotation angle in the 2D Helmert given in arc seconds.
+dx=<value>
Translation rate of the x-axis given in m/year.
+dy=<value>
Translation rate of the y-axis given in m/year.
+dz=<value>
Translation rate of the z-axis given in m/year.

+ds=<value>
Scale rate factor given in ppm/year.
+drx=<value>
Rotation rate of the x-axis given in arc seconds/year.
+dry=<value>
Rotation rate of the y-axis given in arc seconds/year.
+drz=<value>
Rotation rate of the y-axis given in arc seconds/year.
+t_epoch=<value>
Central epoch of transformation given in decimalyear. Only used spatiotemporal transformations.
+t_obs=<value>
Observation time of coordinate(s) given in decicalyear. Mostly useful in 2D and 3D transformations where the
observation time is not passed as part of the input coordinate. Can be used to override the observation time from
the input coordinate.
+exact
Use exact transformation equations.
See (6.6)
+transpose
Transpose rotation matrix and follow the Cordinate Frame rotation convention. If +transpose is not added
the Position Vector rotation convention is used.
Mathematical description
In the notation used below, 𝑃ˆ is the rate of change of a given transformation parameter 𝑃 . 𝑃˙ is the kinematically
adjusted version of 𝑃 , described by
𝑃˙ = 𝑃 + 𝑃ˆ (𝑡 − 𝑡𝑐𝑒𝑛𝑡𝑟𝑎𝑙 ) (6.1)
where 𝑡 is the observation time of the coordinate and 𝑡𝑐𝑒𝑛𝑡𝑟𝑎𝑙 is the central epoch of the transformation. Equation (6.1)
can be used to propagate all transformation parameters in time.
Superscripts of vectors denote the reference frame the coordinates in the vector belong to.
2D Helmert
The simplest version of the Helmert transform is the 2D case. In the 2-dimensional case only the horizontal coordinates
are changed. The coordinates can be translated, rotated and scale. Translation is controlled with the x and y parameters.
The rotation is determined by theta and the scale is controlled with the s parameters.
Note: The scaling parameter s is unitless for the 2D Helmert, as opposed to the 3D version where the scaling
parameter is given in units of ppm.
Mathematically the 2D Helmert is described as:

[︂ ]︂𝐵 [︂ ]︂ [︂ ]︂ [︂ ]︂𝐴
𝑋 𝑇𝑥 cos 𝜃 sin 𝜃 𝑋
= +𝑠 (6.2)
𝑌 𝑇𝑦 − sin 𝜃 cos 𝜃 𝑌

(6.2) can be extended to a time-varying kinematic version by adjusting the parameters with (6.1) to (6.2), which yields
the kinematic 2D Helmert transform:
[︂ ]︂𝐵 [︂ ]︂ ]︂ [︂ ]︂𝐴
𝑇˙𝑥 cos 𝜃˙ sin 𝜃˙ 𝑋
[︂
𝑋
= ˙ + 𝑠(𝑡) (6.2)
𝑌 𝑇𝑦 − sin 𝜃˙ cos 𝜃˙ 𝑌
All parameters in (6.2) are determined by the use of (6.1), which applies the rate of change to each individual parameter
for a given timespan between 𝑡 and 𝑡𝑐𝑒𝑛𝑡𝑟𝑎𝑙 .
3D Helmert
The general form of the 3D Helmert is
𝑉 𝐵 = 𝑇 + 1 + 𝑠 × 10−6 R𝑉 𝐴
(︀ )︀
(6.2)
Where 𝑇 is a vector consisting of the three translation parameters, 𝑠 is the scaling factor and R is a rotation matrix.
𝑉 𝐴 and 𝑉 𝐵 are coordinate vectors, with 𝑉 𝐴 being the input coordinate and 𝑉 𝐵 is the output coordinate.
The rotation matrix is composed of three rotation matrices, one for each axis:
⎡ ⎤
1 0 0
R𝑋 = ⎣0 cos 𝜑 − sin 𝜑⎦ (6.2)
0 sin 𝜑 cos 𝜑
⎡ ⎤
cos 𝜃 0 sin 𝜃
R𝑌 = ⎣ 0 1 0 ⎦ (6.3)
− sin 𝜃 0 cos 𝜃
⎡ ⎤
cos 𝜓 − sin 𝜓 0
R𝑍 = ⎣ sin 𝜓 cos 𝜓 0⎦ (6.4)
0 0 1
The three rotation matrices can be combined in one:
R = RX RY RY (6.5)
For R, this yields:

⎡ ⎤
cos 𝜃 cos 𝜓 − cos 𝜑 sin 𝜓 + sin 𝜑 sin 𝜃 cos 𝜓 sin 𝜑 sin 𝜓 + cos 𝜑 sin 𝜃 cos 𝜓
⎣ cos 𝜃 sin 𝜓 cos 𝜑 cos 𝜓 + sin 𝜑 sin 𝜃 sin 𝜓 − sin 𝜑 cos 𝜓 + cos 𝜑 sin 𝜃 sin 𝜓 ⎦ (6.6)
− sin 𝜃 sin 𝜑 cos 𝜃 cos 𝜑 cos 𝜃
Using the small angle approxition the rotation matrix can be simplified to
⎡ ⎤
1 −𝑅𝑧 𝑅𝑦
R = ⎣ 𝑅𝑧 1 −𝑅𝑥 ⎦ (6.7)
−𝑅𝑦 𝑅𝑥 1
Which allow us to express the most common version of the Helmert transform, using the approximated rotation matrix:
⎡ ⎤𝐵 ⎡ ⎤ ⎡ ⎤ ⎡ ⎤𝐴
𝑋 𝑇𝑥 1 −𝑅𝑧 𝑅𝑦 𝑋
⎣ 𝑌 ⎦ = ⎣𝑇𝑦 ⎦ + 1 + 𝑠 × 10−6 ⎣ 𝑅𝑧
(︀ )︀
1 −𝑅𝑥 ⎦ ⎣ 𝑌 ⎦ (6.7)
𝑍 𝑇𝑧 −𝑅𝑦 𝑅𝑥 1 𝑍
If the rotation matrix is transposed the transformation is effectively reversed. This is cause for some confusion since
there is no correct way of defining the rotation matrix. Two conventions exists and they seem to be equally pop-
ular. PROJ uses the Position Vector rotation convention. The rotation matrix can be transposed by adding the
+transpose flag in the transformation setup which makes PROJ follow the Coordinate Frame rotation convention.

Applying (6.1) we get the kinematic version of the approximated 3D Helmert:

⎡ ⎤𝐵 ⎡ ⎤ ⎤ ⎡ ⎤𝐴
𝑇˙𝑥 −𝑅˙𝑧 𝑅˙𝑦
⎡
𝑋 1 𝑋
⎣ 𝑌 ⎦ = ⎣𝑇˙𝑦 ⎦ + 1 + 𝑠˙ × 10−6 ⎣ 𝑅˙𝑧 −𝑅˙𝑥 ⎦ ⎣ 𝑌 ⎦
(︀ )︀
1 (6.7)
𝑍 𝑇˙𝑧 −𝑅˙𝑦 𝑅˙𝑥 1 𝑍
The Helmert transformation can be applied without using the rotation parameters, in which case it becomes a simple
translation of the origin of the coordinate system. When using the Helmert in this version equation (6.2) simplifies to:
⎡ ⎤𝐵 ⎡ ⎤ ⎡ ⎤𝐴
𝑋 𝑇𝑥 𝑋
⎣ 𝑌 ⎦ = ⎣𝑇𝑦 ⎦ + ⎣ 𝑌 ⎦ (6.7)
𝑍 𝑇𝑧 𝑍
That after application of (6.1) has the following kinematic counterpart:

⎡ ⎤𝐵 ⎡ ⎤ ⎡ ⎤𝐴
𝑋 𝑇˙𝑥 𝑋
⎣ 𝑌 ⎦ = ⎣𝑇˙𝑦 ⎦ + ⎣ 𝑌 ⎦ (6.7)
𝑍 𝑇˙𝑧 𝑍
6.3.3 Molodensky transform

The Molodensky transformation resembles a Helmert transform with zero rotations and a scale of unity, but con-
verts directly from geodetic coordinates to geodetic coordinates, without the intermediate shifts to and from cartesian
geocentric coordinates, associated with the Helmert transformation. The Molodensky transformation is simple to im-
plement and to parameterize, requiring only the 3 shifts between the input and output frame, and the corresponding
differences between the semimajor axes and flattening parameters of the reference ellipsoids. Due to its algorith-
mic simplicity, it was popular prior to the ubiquity of digital computers. Today, it is mostly interesting for historical
reasons, but nevertheless indispensable due to the large amount of data that has already been transformed that way
[EversKnudsen2017].
Alias molodensky
Domain 3D
Input type Geodetic coordinates (horizontal), meters (vertical)
output type Geodetic coordinates (horizontal), meters (vertical)
The Molodensky transform can be used to perform a datum shift from coordinate (𝜑1 , 𝜆1 , ℎ1 ) to (𝜑2 , 𝜆2 , ℎ2 ) where
the two coordinates are referenced to different ellipsoids. This is based on three assumptions:
1. The cartesian axes, 𝑋, 𝑌, 𝑍, of the two ellipsoids are parallel.
2. The offset, 𝛿𝑋, 𝛿𝑌, 𝛿𝑍, between the two ellipsoid are known.
3. The characteristics of the two ellipsoids, expressed as the difference in semimajor axis (𝛿𝑎) and flattening (𝛿𝑓 ),
are known.
The Molodensky transform is mostly used for transforming between old systems dating back to the time before com-
puters. The advantage of the Molodensky transform is that it is fairly simple to compute by hand. The ease of
computation come at the cost of limited accuracy.
A derivation of the mathematical formulas for the Molodensky transform can be found in [Deakin2004].

Examples
The abridged Molodensky:
proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8 dx=-134 dy=-48 dz=149

˓→abridged
The same transformation using the standard Molodensky:
proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8 dx=-134 dy=-48 dz=149
Parameters
Required
+da=<value>
Difference in semimajor axis of the defining ellipsoids.
+df=<value>
Difference in flattening of the defining ellipsoids.
+dx=<value>
Offset of the X-axes of the defining ellipsoids.
+dy=<value>
Offset of the Y-axes of the defining ellipsoids.
+dz=<value>
Offset of the Z-axes of the defining ellipsoids.
+ellps=<value>
Optional
+abridged
Use the abridged version of the Molodensky transform.
6.3.4 Horizontal grid shift

Change of horizontal datum by grid shift.

Input type Geodetic coordinates (horizontal), meters (vertical), decimalyear (temporal)
Output type Geodetic coordinates (horizontal), meters (vertical), decimalyear (temporal)
The horizontal grid shift is done by offsetting the planar input coordinates by a specific amount determined by the
loaded grids. The simplest use case of the horizontal grid shift is applying a single grid:

+proj=hgridshift +grids=nzgr2kgrid0005.gsb
More than one grid can be loaded at the same time, for instance in case the dataset needs to be transformed spans
several countries. In this example grids of the continental US, Alaska and Canada is loaded at the same time:
+proj=hgridshift +grids=@conus,@alaska,@ntv2_0.gsb,@ntv_can.dat
The @ in the above example states that the grid is optional, in case the grid is not found in the PROJ search path. The
list of grids is prioritized so that grids in the start of the list takes precedence over the grids in the back of the list.
PROJ supports CTable2, NTv1 and NTv2 files for horizontal grid corrections. Details about all three formats can be
found in the GDAL documentation. GDAL reads and writes all three formats. Using GDAL for construction of new
grids is recommended.
Temporal gridshifting

By initializing the horizontal gridshift operation with a central epoch, it can be used as a step function applying the
grid offsets only if a coordinate is transformed from an epoch before grids central epoch to an epoch after. This is
handy in transformations where it is necessary to handle deformations caused by seismic activity.
The central epoch of the grid is controlled with +t_epoch and the final epoch of the coordinate is set with
+t_final. The observation epoch of the coordinate is part of the coordinate tuple.
Suppose we want to model the deformation of the 2008 earthquake in Iceland in a transformation of data from 2005
to 2009:
echo 63.992 -21.014 10.0 2005.0 | cct +proj=hgridshift +grids=iceland2008.gsb +t_

˓→epoch=2008.4071 +t_final=2009.0
63.9920021 -21.0140013 10.0 2005.0
Note: The timestamp of the resulting coordinate is still 2005.0. The observation time is always kept unchanged as it
would otherwise be impossible to do the inverse transformation.
Temporal gridshifting is especially powerful in transformation pipelines where several gridshifts can be chained to-
gether, effectively acting as a series of step functions that can be applied to a coordinate that is propagated through
time. In the following example we establish a pipeline that allows transformation of coordinates from any given epoch
up until the current date, applying only those gridshifts that have central epochs between the observation epoch and
the final epoch:
+proj=pipeline +t_final=now
+step +proj=hgridshift +grids=earthquake_1.gsb +t_epoch=2010.421
Note: The special epoch now is used when specifying the final epoch with +t_final. This results in coordinates
being transformed to the current date. Additionally, +t_final is used as a global pipeline parameter, which means
that it is applied to all the steps in the pipeline.
In the above transformation, a coordinate with observation epoch 2009.32 would be subject to all three gridshift steps
in the pipeline. A coordinate with observation epoch 2014.12 would only by offset by the last step in the pipeline.

Parameters
Required
+grids=<list>
Comma-separated list of grids to load. If a grid is prefixed by an @ the grid is considered optional and PROJ
Grids are expected to be in CTable2, NTv1 or NTv2 format.
Optional
+t_epoch=<time>
Central epoch of the transformation.
+t_final=<time>
Final epoch that the coordinate will be propagated to after transformation. The special epoch now can be used
instead of writing a specific period in time. When now is used, it is replaced internally with the epoch of the
transformation. This means that the resulting coordinate will be slightly different if carried out again at a later
date.
6.3.5 Vertical grid shift

Change Vertical datum change by grid shift
Domain 3D and 4D
Input type Geodetic coordinates (horizontal), meters (vertical), decimalyear (temporal)
Output type Geodetic coordinates (horizontal), meters (vertical), decimalyear (temporal)
The vertical grid shift is done by offsetting the vertical input coordinates by a specific amount determined by the
loaded grids. The simplest use case of the horizontal grid shift is applying a single grid. Here we change the vertical
reference from the ellipsoid to the global geoid model, EGM96:
+proj=vgridshift +grids=egm96_16.gtx
More than one grid can be loaded at the same time, for instance in the case where a better geoid model than the global
is available for a certain area. Here the gridshift is set up so that the local DVR90 geoid model takes precedence over
the global model:
+proj=vgridshift [email protected],egm96_16.gtx
The @ in the above example states that the grid is optional, in case the grid is not found in the PROJ search path. The
list of grids is prioritized so that grids in the start of the list takes precedence over the grids in the back of the list.
PROJ supports the GTX file format for vertical grid corrections. Details about all the format can be found in the GDAL
documentation. GDAL both reads and writes the format. Using GDAL for construction of new grids is recommended.

Temporal gridshifting

By initializing the vertical gridshift operation with a central epoch, it can be used as a step function applying the grid
offsets only if a coordinate is transformed from an epoch before grids central epoch to an epoch after. This is handy in
transformations where it is necessary to handle deformations caused by seismic activity.
The central epoch of the grid is controlled with +t_epoch and the final epoch of the coordinate is set with
+t_final. The observation epoch of the coordinate is part of the coordinate tuple.
Suppose we want to model the deformation of the 2008 earthquake in Iceland in a transformation of data from 2005
to 2009:
echo 63.992 -21.014 10.0 2005.0 | cct +proj=vgridshift +grids=iceland2008.gtx +t_

˓→epoch=2008.4071 +t_final=2009.0
63.992 -21.014 10.11 2005.0
Note: The timestamp of the resulting coordinate is still 2005.0. The observation time is always kept unchanged as it
would otherwise be impossible to do the inverse transformation.
Temporal gridshifting is especially powerful in transformation pipelines where several gridshifts can be chained to-
gether, effectively acting as a series of step functions that can be applied to a coordinate that is propagated through
time. In the following example we establish a pipeline that allows transformation of coordinates from any given epoch
up until the current date, applying only those gridshifts that have central epochs between the observation epoch and
the final epoch:
+proj=pipeline +t_final=now
+step +proj=vgridshift +grids=earthquake_1.gtx +t_epoch=2010.421
Note: The special epoch now is used when specifying the final epoch with +t_final. This results in coordinates
being transformed to the current date. Additionally, +t_final is used as a global pipeline parameter, which means
that it is applied to all the steps in the pipeline.
In the above transformation, a coordinate with observation epoch 2009.32 would be subject to all three gridshift steps
in the pipeline. A coordinate with observation epoch 2014.12 would only by offset by the last step in the pipeline.
Parameters
Required
+grids=<list>
Comma-separated list of grids to load. If a grid is prefixed by an @ the grid is considered optional and PROJ
Grids are expected to be in GTX format.

Optional
+t_epoch=<time>
Central epoch of the transformation.
+t_final=<time>
Final epoch that the coordinate will be propagated to after transformation. The special epoch now can be used
instead of writing a specific period in time. When now is used, it is replaced internally with the epoch of the
transformation. This means that the resulting coordinate will be slightly different if carried out again at a later
date.
6.4 The pipeline operator

Construct complex operations by daisy-chaining operations in a sequential pipeline.
Alias pipeline
Input type Any
Output type Any
Note: See the section on Geodetic transformation for a more thorough introduction to the concept of transformation
pipelines in PROJ.
With the pipeline operation it is possible to perform several operations after each other on the same input data. This
feature makes it possible to create transformations that are made up of more than one operation, e.g. performing a
datum shift and then applying a suitable map projection. Theoretically any transformation between two coordinate
reference systems is possible to perform using the pipeline operation, provided that the necessary coordinate operations
in each step is available in PROJ.
A pipeline is made up of a number of steps, with each step being a coordinate operation in itself. By connecting
these individual steps sequentially we end up with a concatenated coordinate operation. An example of this is a
transformation from geodetic coordinates on the GRS80 ellipsoid to a projected system where the east-west and north-
east axes has been swapped:
+proj=pipeline +ellps=GRS80 +step +proj=merc +step +proj=axisswap +order=2,1
Here the first step is applying the Mercator projection and the second step is applying the Axis swap conversion. Note
that the +ellps=GRS80 is specified before the first occurrence of +step. This means that the GRS80 ellipsoid is used
in both steps, since any parameter stated before the first occurrence of +step is treated as a global parameter and is
transferred to each individual steps.
6.4.1 Rules for pipelines
1. Pipelines must consist of at least one step.

+proj=pipeline
Will result in an error.

2. Pipelines can only be nested if the nested pipeline is defined in an init-file.
+proj=pipeline
+step +proj=pipeline +step +proj=merc +step +proj=axisswap +order=2,1
Results in an error, while

+proj=pipeline
+step +init=predefined_pipelines:projectandswap
does not.
3. Pipelines without a forward path can’t be constructed.
+proj=pipeline +step +inv +proj=urm5
Will result in an error since Urmaev V does not have an inverse operation defined.
4. Parameters added before the first ‘+step‘ are global and will be applied to all steps.
In the following the GRS80 ellipsoid will be applied to all steps.
+proj=pipeline +ellps=GRS80
+step +proj=cart
+step +proj=helmert +x=10 +y=3 +z=1
+step +proj=cart +inv
+step +proj=merc
5. Units of operations must match between steps.

The output units of step n must match the expected input unit of step n+1. E.g., you can’t pass an operation that
outputs projected coordinates to an operation that expects angular units (degrees). An example of such a unit mismatch
is displayed below.
+proj=pipeline
+step +proj=merc # Mercator outputs projected coordinates
+step +proj=robin # The Robinson projection expects angular input
6.4.2 Parameters
Required
+step
Separate each step in a pipeline.
Optional
+inv
Invert a step in a pipeline.
6.4. The pipeline operator 149


CHAPTER
SEVEN
RESOURCE FILES
A number of files containing preconfigured transformations and default parameters for certain projections are bundled
with the PROJ distribution. Init files contains preconfigured proj-strings for various coordinate reference systems and
the defaults file contains default values for parameters of select projections.
In addition to the bundled init-files the PROJ.4 project also distribute a number of packages containing transformation
grids and additional init-files not included in the main PROJ package.
7.1 External resources
For a functioning PROJ installation of the proj-datumgrid is needed. If you have installed PROJ from a package system
chances are that this will already be done for you. The proj-datumgrid package provides transformation grids that are
essential for many of the predefined transformations in PROJ. Which grids are included in the package can be seen on
the proj-datumgrid repository as well as descriptions of those grids.
In addition to the default proj-datumgrid package regional packages are also distributed. These include grids and
init-files that are valid within the given region. The packages are divided into geographical regions in order to keep
the needed disk space by PROJ at a minimum. Some users may have a use for resource files covering several regions
in which case they can download more than one.
At the moment three regional resource file packages are distributed:
• Europe
• Oceania
• North America
Click the links to jump to the relevant README files for each package. Details on the content of the packages
maintained there.
Links to the resource packages can be found in the download section.
7.2 Transformation grids
Grid files are important for shifting and transforming between datums.
PROJ supports CTable2, NTv1 and NTv2 files for horizontal grid corrections and the GTX file format for vertical
corrections. Details about the formats can be found in the GDAL documentation. GDAL reads and writes all formats.
Using GDAL for construction of new grids is recommended.
Below is a given a list of grid resources for various countries which are not included in the grid distributions mentioned
above.
151
7.2.1 Free grids
Below is a list of grids distributed under a free and open license.
Switzerland
Background in ticket #145

We basically have two shift grids available. An official here:
Swiss CHENyx06 dataset in NTv2 format
And a derived in a temporary location which is probably going to disappear soon.
Main problem seems to be there’s no mention of distributivity of the grid from the official website. It just tells: “you
can use freely”. The “contact” link is also broken, but maybe someone could make a phone call to ask for rephrasing
that.
Hungary
Hungarian grid ETRS89 - HD72/EOV (epsg:23700), both horizontal and elevation grids
7.2.2 Non-Free Grids
Not all grid shift files have licensing that allows them to be freely distributed, but can be obtained by users through
free and legal methods.
Canada NTv2.0
Although NTv1 grid shifts are provided freely with PROJ, the higher-quality NTv2.0 file needs to be downloaded from
Natural Resources Canada. More info: http://www.geod.nrcan.gc.ca/tools-outils/ntv2_e.php.
Procedure:
1. Visit the NTv2, and register/login
2. Follow the Download NTv2 link near the bottom of the page.
3. Unzip ntv2_100325.zip (or similar), and move the grid shift file NTV2_0.GSB to the proj directory
(be sure to change the name to lowercase for consistency) e.g.: mv NTV2_0.GSB /usr/local/share/
proj/ntv2_0.gsb
4. Test it using:
cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb +to +proj=latlong

˓→+ellps=GRS80 +datum=NAD83
-111 50
111d0'3.006"W 50d0'0.103"N 0.000 # correct answer
Australia
Geocentric Datum of Australia AGD66/AGD84
152 Chapter 7. Resource files

Canada
Canadian NTv2 grid shift binary for NAD27 <=> NAD83.
Germany
German BeTA2007 DHDN GK3 => ETRS89/UTM
Great Britain
Great Britain’s OSTN15_NTv2: OSGB 1936 => ETRS89

Great Britain’s OSTN02_NTv2: OSGB 1936 => ETRS89
Austria
Austrian Grid for MGI
Spain
Spanish grids for ED50.
Portugal
Portuguese grids for ED50, Lisbon 1890, Lisbon 1937 and Datum 73
Brazil
Brazilian grids for datums Corrego Alegre 1961, Corrego Alegre 1970-72, SAD69 and SAD69(96)
South Africa
South African grid (Cape to Hartebeesthoek94 or WGS84)
Netherlands
Dutch grid (Registration required before download)
7.2.3 HARN
With the support of i-cubed, Frank Warmerdam has written tools to translate the HPGN grids from NOAA/NGS from
.los/.las format into NTv2 format for convenient use with PROJ. This project included implementing a .los/.las
reader for GDAL, and an NTv2 reader/writer. Also, a script to do the bulk translation was implemented in https://
github.com/OSGeo/gdal/tree/trunk/gdal/swig/python/samples/loslas2ntv2.py. The command to do the translation was:
loslas2ntv2.py -auto *hpgn.los
7.2. Transformation grids 153

As GDAL uses NAD83/WGS84 as a pivot datum, the sense of the HPGN datum shift offsets were negated to map
from HPGN to NAD83 instead of the other way. The files can be used with PROJ like this:
cs2cs +proj=latlong +datum=NAD83

+to +proj=latlong +nadgrids=./azhpgn.gsb +ellps=GRS80
# input:
-112 34
# output:
111d59'59.996"W 34d0'0.006"N -0.000
This was confirmed against the NGS HPGN calculator.

The grids are available at http://download.osgeo.org/proj/hpgn_ntv2.zip
7.2.4 HTDP
This page documents use of the crs2crs2grid.py script and the HTDP (Horizontal Time Dependent Positioning) grid
shift modelling program from NGS/NOAA to produce PROJ compatible grid shift files for fine grade conversions
between various NAD83 epochs and WGS84. Traditionally PROJ has treated NAD83 and WGS84 as equivalent and
failed to distinguish between different epochs or realizations of those datums. At the scales of much mapping this is
adequate but as interest grows in high resolution imagery and other high resolution mapping this is inadequate. Also,
as the North American crust drifts over time the displacement between NAD83 and WGS84 grows (more than one
foot over the last two decades).
Getting and building HTDP
The HTDP modelling program is in written FORTRAN. The source and documentation can be found on the HTDP
page at http://www.ngs.noaa.gov/TOOLS/Htdp/Htdp.shtml
On linux systems it will be necessary to install gfortran or some FORTRAN compiler. For ubuntu something like the
following should work.
apt-get install gfortran
To compile the program do something like the following to produce the binary “htdp” from the source code.
gfortran htdp.for -o htdp
Getting crs2crs2grid.py
The crs2crs2grid.py script can be found at https://github.com/OSGeo/gdal/tree/trunk/gdal/swig/python/samples/

crs2crs2grid.py
It depends on having the GDAL Python bindings operational. If they are not
Traceback (most recent call last):

File "./crs2crs2grid.py", line 37, in <module>
from osgeo import gdal, gdal_array, osr
ImportError: No module named osgeo

Usage
crs2crs2grid.py
<src_crs_id> <src_crs_date> <dst_crs_id> <dst_crs_year>
[-griddef <ul_lon> <ul_lat> <ll_lon> <ll_lat> <lon_count> <lat_count>]
[-htdp <path_to_exe>] [-wrkdir <dirpath>] [-kwf]
-o <output_grid_name>
-griddef: by default the following values for roughly the continental USA
at a six minute step size are used:
-127 50 -66 25 251 611
-kwf: keep working files in the working directory for review.
crs2crs2grid.py 29 2002.0 8 2002.0 -o nad83_2002.ct2
The goal of crs2crs2grid.py is to produce a grid shift file for a designated region. The region is defined using the
-griddef switch. When missing a continental US region is used. The script creates a set of sample points for the grid
definition, runs the “htdp” program against it and then parses the resulting points and computes a point by point shift
to encode into the final grid shift file. By default it is assumed the htdp program will be in the executable path. If not,
please provide the path to the executable using the -htdp switch.
The htdp program supports transformations between many CRSes and for each (or most?) of them you need to provide
a date at which the CRS is fixed. The full set of CRS Ids available in the HTDP program are:
1...NAD_83(2011) (North America tectonic plate fixed)

29...NAD_83(CORS96) (NAD_83(2011) will be used)
30...NAD_83(2007) (NAD_83(2011) will be used)
2...NAD_83(PA11) (Pacific tectonic plate fixed)
31...NAD_83(PACP00) (NAD 83(PA11) will be used)
3...NAD_83(MA11) (Mariana tectonic plate fixed)
32...NAD_83(MARP00) (NAD_83(MA11) will be used)
4...WGS_72 16...ITRF92
5...WGS_84(transit) = NAD_83(2011) 17...ITRF93
6...WGS_84(G730) = ITRF92 18...ITRF94 = ITRF96
7...WGS_84(G873) = ITRF96 19...ITRF96
8...WGS_84(G1150) = ITRF2000 20...ITRF97
9...PNEOS_90 = ITRF90 21...IGS97 = ITRF97
10...NEOS_90 = ITRF90 22...ITRF2000
11...SIO/MIT_92 = ITRF91 23...IGS00 = ITRF2000
12...ITRF88 24...IGb00 = ITRF2000
13...ITRF89 25...ITRF2005
14...ITRF90 26...IGS05 = ITRF2005
15...ITRF91 27...ITRF2008
28...IGS08 = ITRF2008
The typical use case is mapping from NAD83 on a particular date to WGS84 on some date. In this case the source
CRS Id “29” (NAD_83(CORS96)) and the destination CRS Id is “8 (WGS_84(G1150)). It is also necessary to select
the source and destination date (epoch). For example:
crs2crs2grid.py 29 2002.0 8 2002.0 -o nad83_2002.ct2
The output is a CTable2 format grid shift file suitable for use with PROJ (4.8.0 or newer). It might be utilized something
like:
cs2cs +proj=latlong +ellps=GRS80 +nadgrids=./nad83_2002.ct2 +to +proj=latlong

˓→+datum=WGS84
7.2. Transformation grids 155

See Also
• http://www.ngs.noaa.gov/TOOLS/Htdp/Htdp.shtml - NGS/NOAA page about the HTDP model and program.

Source for the HTDP program can be downloaded from here.
7.3 Init files
Init files are used for preconfiguring proj-strings for often used transformations, such as those found in the EPSG
database. Most init files contain transformations from a given coordinate reference system to WGS84. This makes
it easy to transformations between any two coordinate reference systems with cs2cs. Init files can however contain
any proj-string and don’t necessarily have to follow the cs2cs paradigm where WGS84 is used as a pivot datum. The
ITRF init file is a good example of that.
A number of init files come pre-bundled with PROJ but it is also possible to add your own custom init files. PROJ
looks for the init files in the directory listed in the PROJ_LIB environment variable.
The format of init files made up of a identifier in angled brackets and a proj-string:
<3819> +proj=longlat +ellps=bessel

+towgs84=595.48,121.69,515.35,4.115,-2.9383,0.853,-3.408 +no_defs <>
The above example is the first entry from the epsg init file. So, this is the coordinate reference system with ID 3819
in the EPSG database. Comments can be inserted by prefixing them with a “#”. With version 4.10.0 a new special
metadata entry is now accepted in init files. It can be parsed with a function from the public API. The metadata entry
in the epsg init file looks like this at the time of writing:
<metadata> +version=9.0.0 +origin=EPSG +lastupdate=2017-01-10
Pre-configured proj-strings from init files are used in the following way:
$ cs2cs -v +proj=latlong +to +init=epsg:3819

# ---- From Coordinate System ----
#Lat/long (Geodetic alias)
#
# +proj=latlong +ellps=WGS84
# ---- To Coordinate System ----
#Lat/long (Geodetic alias)
#
# +init=epsg:3819 +proj=longlat +ellps=bessel
# +towgs84=595.48,121.69,515.35,4.115,-2.9383,0.853,-3.408 +no_defs
It is possible to override parameters when using +init. Just add the parameter to the proj-string alongside the +init
parameter. For instance by overriding the ellipsoid as in the following example
+init=epsg:25832 +ellps=intl
where the Hayford ellipsoid is used instead of the predefined GRS80 ellipsoid. It is also possible to add additional
parameters not specified in the init file, for instance by adding an observation epoch when transforming from ITRF2000
to ITRF2005:
+init=ITRF2000:ITRF2005 +t_obs=2010.5
which then expands to

+proj=helmert +x=-0.0001 +y=0.0008 +z=0.0058 +s=-0.0004

+dx=0.0002 +dy=-0.0001 +dz=0.0018 +ds=-0.000008
+t_epoch=2000.0 +transpose
+t_obs=2010.5
Below is a list of the init files that are packaged with PROJ.
Name Description
esri Auto-generated mapping from Esri projection index. Not maintained any more
epsg EPSG database
GL27 Great Lakes Grids
IGNF French coordinate systems supplied by the IGNF
ITRF2000 Full set of transformation parameters between ITRF2000 and other ITRF’s
nad27 State plane coordinate systems, North American Datum 1927
nad83 State plane coordinate systems, North American Datum 1983
7.4 The defaults file
The proj_def.dat file supplies default parameters for PROJ. It uses the same syntax as the init files described
above. The identifiers in the defaults file describe to what the parameters should apply. If the <general> identifier
is used, then all parameters in that section applies for all proj-strings. Otherwise the identifier is connected to a
specific projection. With the defaults file supplied with PROJ the default ellipsoid is set to WGS84 (for all proj-
strings). Apart from that only the Albers Equal Area, Lambert Conic Conformal and the Lagrange projections have
default parameters. Defaults can be ignored by adding the +no_def parameter to a proj-string.
7.4. The defaults file 157


CHAPTER
EIGHT
GEODESIC CALCULATIONS
8.1 Introduction
Consider an ellipsoid of revolution with equatorial radius 𝑎, polar semi-axis 𝑏, and flattening 𝑓 = (𝑎 − 𝑏)/𝑎. Points
on the surface of the ellipsoid are characterized by their latitude 𝜑 and longitude 𝜆. (Note that latitude here means the
geographical latitude, the angle between the normal to the ellipsoid and the equatorial plane).
The shortest path between two points on the ellipsoid at (𝜑1 , 𝜆1 ) and (𝜑2 , 𝜆2 ) is called the geodesic. Its length is 𝑠12
and the geodesic from point 1 to point 2 has forward azimuths 𝛼1 and 𝛼2 at the two end points. In this figure, we have
𝜆12 = 𝜆2 − 𝜆1 .
A geodesic can be extended indefinitely by requiring that any sufficiently small segment is a shortest path; geodesics
are also the straightest curves on the surface.
8.2 Solution of geodesic problems
Traditionally two geodesic problems are considered:

• the direct problem — given 𝜑1 , 𝜆1 , 𝛼1 , 𝑠12 , determine 𝜑2 , 𝜆2 , 𝛼2 .
• the inverse problem — given 𝜑1 , 𝜆1 , 𝜑2 , 𝜆2 , determine 𝑠12 , 𝛼1 , 𝛼2 .
PROJ incorporates C library for Geodesics from GeographicLib. This library provides routines to solve the direct and
1
inverse geodesic problems. Full double precision accuracy is maintained provided that |𝑓 | < 50 . Refer to the
application programming interface
for full documentation. A brief summary of the routines is given in geodesic(3).
The interface to the geodesic routines differ in two respects from the rest of PROJ:
• angles (latitudes, longitudes, and azimuths) are in degrees (instead of in radians);
• the shape of ellipsoid is specified by the flattening 𝑓 ; this can be negative to denote a prolate ellipsoid; setting
𝑓 = 0 corresponds to a sphere, in which case the geodesic becomes a great circle.
PROJ also includes a command line tool, geod(1), for performing simple geodesic calculations.
8.3 Additional properties
The routines also calculate several other quantities of interest
159
• 𝑆12 is the area between the geodesic from point 1 to point 2 and the equator; i.e., it is the area, measured counter-
clockwise, of the quadrilateral with corners (𝜑1 , 𝜆1 ), (0, 𝜆1 ), (0, 𝜆2 ), and (𝜑2 , 𝜆2 ). It is given in meters2 .
• 𝑚12 , the reduced length of the geodesic is defined such that if the initial azimuth is perturbed by 𝑑𝛼1 (radians)
then the second point is displaced by 𝑚12 𝑑𝛼1 in the direction perpendicular to the geodesic. 𝑚12 is given in
meters. On a curved surface the reduced length obeys a symmetry relation, 𝑚12 + 𝑚21 = 0. On a flat surface,
we have 𝑚12 = 𝑠12 .
• 𝑀12 and 𝑀21 are geodesic scales. If two geodesics are parallel at point 1 and separated by a small distance
:math‘dt‘, then they are separated by a distance 𝑀12 𝑑𝑡 at point 2. 𝑀21 is defined similarly (with the geodesics
being parallel to one another at point 2). 𝑀12 and 𝑀21 are dimensionless quantities. On a flat surface, we have
𝑀12 = 𝑀21 = 1.
• 𝜎12 is the arc length on the auxiliary sphere. This is a construct for converting the problem to one in spherical
trigonometry. The spherical arc length from one equator crossing to the next is always 180∘ .
If points 1, 2, and 3 lie on a single geodesic, then the following addition rules hold:
• 𝑠13 = 𝑠12 + 𝑠23 ,
• 𝜎13 = 𝜎12 + 𝜎23 ,
• 𝑆13 = 𝑆12 + 𝑆23 ,
• 𝑚13 = 𝑚12 𝑀23 + 𝑚23 𝑀21 ,
• 𝑀13 = 𝑀12 𝑀23 − (1 − 𝑀12 𝑀21 )𝑚23 /𝑚12 ,
• 𝑀31 = 𝑀32 𝑀21 − (1 − 𝑀23 𝑀32 )𝑚12 /𝑚23 .
8.4 Multiple shortest geodesics
The shortest distance found by solving the inverse problem is (obviously) uniquely defined. However, in a few special
cases there are multiple azimuths which yield the same shortest distance. Here is a catalog of those cases:
• 𝜑1 = −𝜑2 (with neither point at a pole). If 𝛼1 = 𝛼2 , the geodesic is unique. Otherwise there are two geodesics
and the second one is obtained by setting [𝛼1 , 𝛼2 ] ← [𝛼2 , 𝛼1 ], [𝑀12 , 𝑀21 ] ← [𝑀21 , 𝑀12 ], 𝑆12 ← −𝑆12 . (This
occurs when the longitude difference is near ±180∘ for oblate ellipsoids.)
• 𝜆2 = 𝜆1 ± 180∘ (with neither point at a pole). If 𝛼1 = 0∘ or ±180∘ , the geodesic is unique. Otherwise there
are two geodesics and the second one is obtained by setting [𝛼1 , 𝛼2 ] ← [−𝛼1 , −𝛼2 ], 𝑆12 ← −𝑆12 . (This occurs
when 𝜑2 is near −𝜑1 for prolate ellipsoids.)
• Points 1 and 2 at opposite poles. There are infinitely many geodesics which can be generated by setting
[𝛼1 , 𝛼2 ] ← [𝛼1 , 𝛼2 ] + [𝛿, −𝛿], for arbitrary 𝛿. (For spheres, this prescription applies when points 1 and 2
are antipodal.)
• 𝑠12 = 0 (coincident points). There are infinitely many geodesics which can be generated by setting [𝛼1 , 𝛼2 ] ←
[𝛼1 , 𝛼2 ] + [𝛿, 𝛿], for arbitrary 𝛿.
8.5 Background
The algorithms implemented by this package are given in [Karney2013] and are based on [Bessel1825] and
[Helmert1880]; the algorithm for areas is based on [Danielsen1989]. These improve on the work of [Vincenty1975]
in the following respects:
• The results are accurate to round-off for terrestrial ellipsoids (the error in the distance is less then 15 nanometers,
compared to 0.1 mm for Vincenty).
160 Chapter 8. Geodesic calculations

• The solution of the inverse problem is always found. (Vincenty’s method fails to converge for nearly antipodal
points.)
• The routines calculate differential and integral properties of a geodesic. This allows, for example, the area of a
geodesic polygon to be computed.
Additional background material is provided in [GeodesicBib], [GeodesicWiki], and [Karney2011].
8.5. Background 161

162 Chapter 8. Geodesic calculations

CHAPTER
NINE
DEVELOPMENT
These pages are primarily focused towards developers either contributing to the PROJ project or using the library in
their own software.
9.1 Quick start
This is a short introduction to the PROJ API. In the following section we create a simple program that transforms a
geodetic coordinate to UTM and back again. The program is explained a few lines at a time. The complete program
can be seen at the end of the section.
See the following sections for more in-depth descriptions of different parts of the PROJ API or consult the API
reference for specifics.
Before the PROJ API can be used it is necessary to include the proj.h header file. Here stdio.h is also included
so we can print some text to the screen:
#include <stdio.h>
#include <proj.h>
Let’s declare a few variables that’ll be used later in the program. Each variable will be discussed below. See the
reference for more info on data types.
PJ_CONTEXT *C;
PJ *P;
PJ_COORD a, b;
For use in multi-threaded programs the PJ_CONTEXT threading-context is used. In this particular example it is not
needed, but for the sake of completeness it created here. The section on threads discusses this in detail.
/* use PJ objects from only one thread */
Next we create the PJ transformation object P with the function proj_create. proj_create takes the threading
context C created above, and a proj-string that defines the desired transformation. Here we transform from geodetic
coordinate to UTM zone 32N. It is recommended to create one threading-context per thread used by the program. This
ensures that all PJ objects created in the same context will be sharing resources such as error-numbers and loaded
grids. In case the creation of the PJ object fails an error message is displayed and the program returns. See Error
handling for further details.
P = proj_create (C, "+proj=utm +zone=32 +ellps=GRS80");

if (0==P)
163
PROJ uses it’s own data structures for handling coordinates. Here we use a PJ_COORD which is easily assigned with
the function proj_coord. Note that the input values are converted to radians with proj_torad. This is necessary
since PROJ is using radians internally. See Transformations for further details.
/* note: PROJ.4 works in radians, hence the proj_torad() calls */
The coordinate defined above is transformed with proj_trans_coord. For this a PJ object, a transformation
direction (either forward or inverse) and the coordinate is needed. The transformed coordinate is returned in b. Here
the forward (PJ_FWD) transformation from geodetic to UTM is made.
/* transform to UTM zone 32, then back to geographical */

b = proj_trans (P, PJ_FWD, a);
The inverse transformation (UTM to geodetic) is done similar to above, this time using PJ_INV as the direction.
printf ("easting: %g, northing: %g\n", b.enu.e, b.enu.n);

b = proj_trans (P, PJ_INV, b);
Before ending the program the allocated memory needs to be released again:
/* Clean up */
proj_destroy (P);
A complete compilable version of the above can be seen here:
1 #include <stdio.h>
2 #include <proj.h>
3
4 int main (void) {

5 PJ_CONTEXT *C;
6 PJ *P;
7 PJ_COORD a, b;
8
9 /* or you may set C=PJ_DEFAULT_CTX if you are sure you will */

10 /* use PJ objects from only one thread */
11 C = proj_context_create();
12
13 P = proj_create (C, "+proj=utm +zone=32 +ellps=GRS80");

14 if (0==P)
15 return puts ("Oops"), 0;
16
17 /* a coordinate union representing Copenhagen: 55d N, 12d E */

18 /* note: PROJ.4 works in radians, hence the proj_torad() calls */
19 a = proj_coord (proj_torad(12), proj_torad(55), 0, 0);
20
21 /* transform to UTM zone 32, then back to geographical */

22 b = proj_trans (P, PJ_FWD, a);
23 printf ("easting: %g, northing: %g\n", b.enu.e, b.enu.n);
24 b = proj_trans (P, PJ_INV, b);
25 printf ("longitude: %g, latitude: %g\n", b.lp.lam, b.lp.phi);
26
27 /* Clean up */
28 proj_destroy (P);
29 proj_context_destroy (C); /* may be omitted in the single threaded case */
30 return 0;
31 }
164 Chapter 9. Development

9.2 Transformations
9.3 Error handling
9.4 Threads
This page is about efforts to make PROJ thread safe.
9.4.1 Key Thread Safety Issues
• the global pj_errno variable is shared between threads and makes it essentially impossible to handle errors safely.
Being addressed with the introduction of the projCtx execution context.
• the datum shift using grid files uses globally shared lists of loaded grid information. Access to this has been
made safe in 4.7.0 with the introduction of a PROJ mutex used to protect access to these memory structures (see
pj_mutex.c).
9.4.2 projCtx
Primarily in order to avoid having pj_errno as a global variable, a “thread context” structure has been introduced into a
variation of the PROJ API for the 4.8.0 release. The pj_init() and pj_init_plus() functions now have context variations
called pj_init_ctx() and pj_init_plus_ctx() which take a projections context.
The projections context can be created with pj_ctx_alloc(), and there is a global default context used when one is not
provided by the application. There is a pj_ctx_ set of functions to create, manipulate, query, and destroy contexts. The
contexts are also used now to handle setting debugging mode, and to hold an error reporting function for textual error
and debug messages. The API looks like:
projPJ pj_init_ctx( projCtx, int, char ** );

projPJ pj_init_plus_ctx( projCtx, const char * );
projCtx pj_get_default_ctx(void);
projCtx pj_get_ctx( projPJ );
void pj_set_ctx( projPJ, projCtx );
projCtx pj_ctx_alloc(void);
void pj_ctx_free( projCtx );
int pj_ctx_get_errno( projCtx );
void pj_ctx_set_errno( projCtx, int );
void pj_ctx_set_debug( projCtx, int );
void pj_ctx_set_logger( projCtx, void (*)(void *, int, const char *) );
void pj_ctx_set_app_data( projCtx, void * );
void *pj_ctx_get_app_data( projCtx );
Multithreaded applications are now expected to create a projCtx per thread using pj_ctx_alloc(). The context’s error
handlers, and app data may be modified if desired, but at the very least each context has an internal error value accessed
with pj_ctx_get_errno() as opposed to looking at pj_errno.
Note that pj_errno continues to exist, and it is set by pj_ctx_set_errno() (as well as setting the context specific er-
ror number), but pj_errno still suffers from the global shared problem between threads and should not be used by
multithreaded applications.
Note that pj_init_ctx(), and pj_init_plus_ctx() will assign the projCtx to the created projPJ object. Functions like
pj_transform(), pj_fwd() and pj_inv() will use the context of the projPJ for error reporting.

9.4.3 src/multistresstest.c
A small multi-threaded test program has been written (src/multistresstest.c) for testing multithreaded use of PROJ. It
performs a series of reprojections to setup a table expected results, and then it does them many times in several threads
to confirm that the results are consistent. At this time this program is not part of the builds but it can be built on linux
like:
gcc -g multistresstest.c .libs/libproj.so -lpthread -o multistresstest

./multistresstest
9.5 Reference
9.5.1 Data types
This section describes the numerous data types in use in PROJ.4. As a rule of thumb PROJ.4 data types are prefixed
with PJ_, or in one particular case, is simply called PJ. A few notable exceptions can be traced back to the very early
days of PROJ.4 when the PJ_ prefix was not consistently used.
Transformation objects
PJ
Object containing everything related to a given projection or transformation. As a user of the PROJ.4 library
you are only exposed to pointers to this object and the contents is hidden behind the public API. PJ objects are
created with proj_create() and destroyed with proj_destroy().
PJ_DIRECTION
Enumeration that is used to convey in which direction a given transformation should be performed. Used in
transformation function call as described in the section on transformation functions.
Forward transformations are defined with the :c:
typedef enum proj_direction {

PJ_FWD = 1, /* Forward */
PJ_IDENT = 0, /* Do nothing */
PJ_INV = -1 /* Inverse */
} PJ_DIRECTION;
PJ_FWD
Perform transformation in the forward direction.
PJ_IDENT
Identity. Do nothing.
PJ_INV
Perform transformation in the inverse direction.
PJ_CONTEXT
Context objects enable safe multi-threaded usage of PROJ.4. Each PJ object is connected to a context
(if not specified, the default context is used). All operations within a context should be performed in the
same thread. PJ_CONTEXT objects are created with proj_context_create() and destroyed with
proj_context_destroy().
PJ_AREA
Opaque object describing an area in which a transformation is performed.

Note: This object is not fully implemented yet. It is to be used with proj_create_crs_to_crs() to
select the best transformation between the two input coordinate reference systems.
2 dimensional coordinates
Various 2-dimensional coordinate data types.

PJ_LP
Geodetic coordinate, latitude and longitude. Usually in radians.
typedef struct { double lam, phi; } PJ_LP;
double PJ_LP.lam
Longitude. Lambda.
double PJ_LP.phi
Latitude. Phi.
PJ_XY
2-dimensional cartesian coordinate.
typedef struct { double x, y; } PJ_XY;
double PJ_XY.x
Easting.
double PJ_XY.y
Northing.
PJ_UV
2-dimensional generic coordinate. Usually used when contents can be either a PJ_XY or PJ_LP.
typedef struct {double u, v; } PJ_UV;
double PJ_UV.u
Longitude or easting, depending on use.
double PJ_UV.v
Latitude or northing, depending on use.
3 dimensional coordinates
The following data types are the 3-dimensional equivalents to the data types above.
PJ_LPZ
3-dimensional version of PJ_LP. Holds longitude, latitude and a vertical component.
typedef struct { double lam, phi, z; } PJ_LPZ;
double PJ_LPZ.lam
Longitude. Lambda.
double PJ_LPZ.phi
Latitude. Phi.
9.5. Reference 167

double PJ_LPZ.z
Vertical component.
PJ_XYZ
Cartesian coordinate in 3 dimensions. Extension of PJ_XY.
typedef struct { double x, y, z; } PJ_XYZ;
double PJ_XYZ.x
Easting or the X component of a 3D cartesian system.
double PJ_XYZ.y
Northing or the Y component of a 3D cartesian system.
double PJ_XYZ.z
Vertical component or the Z component of a 3D cartesian system.
PJ_UVW
3-dimensional extension of PJ_UV .
typedef struct {double u, v, w; } PJ_UVW;
double PJ_UVW.u
Longitude or easting, depending on use.
double PJ_UVW.v
Latitude or northing, depending on use.
double PJ_UVW.w
Vertical component.
Spatiotemporal coordinate types
The following data types are extensions of the triplets above into the time domain.
PJ_LPZT
Spatiotemporal version of PJ_LPZ.
typedef struct {
double lam;
double phi;
double z;
double t;
} PJ_LPZT;
double PJ_LPZT.lam
Longitude.
double PJ_LPZT.phi
Latitude
double PJ_LPZT.z
Vertical component.
double PJ_LPZT.t
Time component.
PJ_XYZT
Generic spatiotemporal coordinate. Useful for e.g. cartesian coordinates with an attached time-stamp.

typedef struct {
double x;
double y;
double z;
double t;
} PJ_XYZT;
double PJ_XYZT.x
Easting or the X component of a 3D cartesian system.
double PJ_XYZT.y
Northing or the Y component of a 3D cartesian system.
double PJ_XYZT.z
Vertical or the Z component of a 3D cartesian system.
double PJ_XYZT.t
Time component.
PJ_UVWT
Spatiotemporal version of PJ_UVW .
typedef struct { double u, v, w, t; } PJ_UVWT;
double PJ_UVWT.e
First horizontal component.
double PJ_UVWT.n
Second horizontal component.
double PJ_UVWT.w
Vertical component.
double PJ_UVWT.t
Temporal component.
Ancillary types for geodetic computations
PJ_OPK
Rotations, for instance three euler angles.
typedef struct { double o, p, k; } PJ_OPK;
double PJ_OPK.o
First rotation angle, omega.
double PJ_OPK.p
Second rotation angle, phi.
double PJ_OPK.k
Third rotation angle, kappa.
Complex coordinate types
PJ_COORD
General purpose coordinate union type, applicable in two, three and four dimensions. This is the default coor-
dinate datatype used in PROJ.
9.5. Reference 169

typedef union {
double v[4];
PJ_XYZT xyzt;
PJ_UVWT uvwt;
PJ_LPZT lpzt;
PJ_XYZ xyz;
PJ_UVW uvw;
PJ_LPZ lpz;
PJ_XY xy;
PJ_UV uv;
PJ_LP lp;
} PJ_COORD ;
double v[4]
Generic four-dimensional vector.
PJ_XYZT PJ_COORD.xyzt
Spatiotemporal cartesian coordinate.
PJ_UVWT PJ_COORD.uvwt
Spatiotemporal generic coordinate.
PJ_LPZT PJ_COORD.lpzt
Longitude, latitude, vertical and time components.
PJ_XYZ PJ_COORD.xyz
PJ_UVW PJ_COORD.uvw
3-dimensional generic coordinate.
PJ_LPZ PJ_COORD.lpz
Longitude, latitude and vertical component.
PJ_XY PJ_COORD.xy
PJ_UV PJ_COORD.uv
2-dimensional generic coordinate.
PJ_LP PJ_COORD.lp
Longitude and latitude.
Projection derivatives
PJ_FACTORS
Various cartographic properties, such as scale factors, angular distortion and meridian convergence. Calculated
with proj_factors().
typedef struct {
double meridional_scale;
double parallel_scale;
double areal_scale;
double angular_distortion;
double meridian_parallel_angle;
double meridian_convergence;


double tissot_semimajor;
double tissot_semiminor;
double dx_dlam;
double dx_dphi;
double dy_dlam;
double dy_dphi;
} PJ_FACTORS;
double PJ_FACTORS.meridional_scale
Meridional scale at coordinate (𝜆, 𝜑).
double PJ_FACTORS.parallel_scale
Parallel scale at coordinate (𝜆, 𝜑).
double PJ_FACTORS.areal_scale
Areal scale factor at coordinate (𝜆, 𝜑).
double PJ_FACTORS.angular_distortion
Angular distortion at coordinate (𝜆, 𝜑).
double PJ_FACTORS.meridian_parallel_angle
Meridian/parallel angle, 𝜃′ , at coordinate (𝜆, 𝜑).
double PJ_FACTORS.meridian_convergence
Meridian convergence at coordinate (𝜆, 𝜑). Sometimes also described as grid declination.
double PJ_FACTORS.tissot_semimajor
Maximum scale factor.
double PJ_FACTORS.tissot_semiminor
Minimum scale factor.
double PJ_FACTORS.dx_dlam
𝜕𝑥
Partial derivative 𝜕𝜆 of coordinate (𝜆, 𝜑).
double PJ_FACTORS.dy_dlam
𝜕𝑦
Partial derivative 𝜕𝜆 of coordinate (𝜆, 𝜑).
double PJ_FACTORS.dx_dphi
𝜕𝑥
Partial derivative 𝜕𝜑 of coordinate (𝜆, 𝜑).
double PJ_FACTORS.dy_dphi
𝜕𝑦
Partial derivative 𝜕𝜑 of coordinate (𝜆, 𝜑).
List structures
PJ_OPERATIONS
Description a PROJ.4 operation
struct PJ_OPERATIONS {
char *id; /* operation keyword */
PJ *(*proj)(PJ *); /* operation entry point */
char * const *descr; /* description text */
};
char *id
Operation keyword.
9.5. Reference 171

PJ *(*op)(PJ *)
Operation entry point.
char * const *
Description of operation.
PJ_ELLPS
Description of ellipsoids defined in PROJ.4
struct PJ_ELLPS {
char *id;
char *major;
char *ell;
char *name;
};
char *id
Keyword name of the ellipsoid.
char *major
Semi-major axis of the ellipsoid, or radius in case of a sphere.
char *ell
Elliptical parameter, e.g. rf=298.257 or b=6356772.2.
char *name
Name of the ellipsoid
PJ_UNITS
Distance units defined in PROJ.
struct PJ_UNITS {
char *id; /* units keyword */
char *to_meter; /* multiply by value to get meters */
char *name; /* comments */
double factor; /* to_meter factor in actual numbers */
};
char *id
Keyword for the unit.
char *to_meter
Text representation of the factor that converts a given unit to meters
char *name
Name of the unit.
double factor
Conversion factor that converts the unit to meters.
PJ_PRIME_MERIDIANS
Prime meridians defined in PROJ.
struct PJ_PRIME_MERIDIANS {
char *id;
char *defn;
};
char *id
Keyword for the prime meridian

char *def
Offset from Greenwich in DMS format.
Info structures
PJ_INFO
Struct holding information about the current instance of PROJ. Struct is populated by proj_info().
typedef struct {
int major;
int minor;
int patch;
const char *release;
const char *version;
const char *searchpath;
} PJ_INFO;
const char *PJ_INFO.release

Release info. Version number and release date, e.g. “Rel. 4.9.3, 15 August 2016”.
const char *PJ_INFO.version
Text representation of the full version number, e.g. “4.9.3”.
int PJ_INFO.major
Major version number.
int PJ_INFO.minor
Minor version number.
int PJ_INFO.patch
Patch level of release.
const char PJ_INFO.searchpath
Search path for PROJ. List of directories separated by semicolons (Windows) or colons (non-Windows),
e.g. “C:\Users\doctorwho;C:\OSGeo4W64\share\proj”. Grids and init files are looked for in directories in
the search path.
PJ_PROJ_INFO
Struct holding information about a PJ object. Populated by proj_pj_info(). The PJ_PROJ_INFO object
provides a view into the internals of a PJ, so once the PJ is destroyed or otherwise becomes invalid, so does
the PJ_PROJ_INFO
typedef struct {
const char *id;
const char *description;
const char *definition;
int has_inverse;
double accuracy;
} PJ_PROJ_INFO;
const char *PJ_PROJ_INFO.id

Short ID of the operation the PJ object is based on, that is, what comes afther the +proj= in a proj-string,
e.g. “merc”.
const char *PJ_PROJ_INFO.description
Long describes of the operation the PJ object is based on, e.g. “Mercator Cyl, Sph&Ell lat_ts=”.
9.5. Reference 173

const char *PJ_PROJ_INFO.definition

The proj-string that was used to create the PJ object with, e.g. “+proj=merc +lat_0=24 +lon_0=53
+ellps=WGS84”.
int PJ_PROJ_INFO.has_inverse
1 if an inverse mapping of the defined operation exists, otherwise 0.
double PJ_PROJ_INFO.accuracy
Expected accuracy of the transformation. -1 if unknown.
PJ_GRID_INFO
Struct holding information about a specific grid in the search path of PROJ. Populated with the function
proj_grid_info().
typedef struct {
char gridname[32];
char filename[260];
char format[8];
LP lowerleft;
LP upperright;
int n_lon, n_lat;
double cs_lon, cs_lat;
} PJ_GRID_INFO;
char PJ_GRID_INFO.gridname[32]
Name of grid, e.g. “BETA2007.gsb”.
char PJ_GRID_INFO
Full path of grid file, e.g. “C:\OSGeo4W64\share\proj\BETA2007.gsb”
char PJ_GRID_INFO.format[8]
File format of grid file, e.g. “ntv2”
LP PJ_GRID_INFO.lowerleft
Geodetic coordinate of lower left corner of grid.
LP PJ_GRID_INFO.upperright
Geodetic coordinate of upper right corner of grid.
int PJ_GRID_INFO.n_lon
Number of grid cells in the longitudinal direction.
int PJ_GRID_INFO.n_lat
Number of grid cells in the latitudianl direction.
double PJ_GRID_INFO.cs_lon
Cell size in the longitudinal direction. In radians.
double PJ_GRID_INFO.cs_lat
Cell size in the latitudinal direction. In radians.
PJ_INIT_INFO
Struct holding information about a specific init file in the search path of PROJ. Populated with the function
proj_init_info().
typedef struct {
char name[32];
char filename[260];
char version[32];
char origin[32];


char lastupdate[16];
} PJ_INIT_INFO;
char PJ_INIT_INFO.name[32]
Name of init file, e.g. “epsg”.
char PJ_INIT_INFO.filename[260]
Full path of init file, e.g. “C:\OSGeo4W64\share\proj\epsg”
char PJ_INIT_INFO.version[32]
Version number of init-file, e.g. “9.0.0”
char PJ_INIT_INFO.origin[32]
Originating entity of the init file, e.g. “EPSG”
char PJ_INIT_INFO.lastupdate
Date of last update of the init-file.
Logging
PJ_LOG_LEVEL
Enum of logging levels in PROJ. Used to set the logging level in PROJ. Usually using proj_log_level().
PJ_LOG_NONE
Don’t log anything.
PJ_LOG_ERROR
Log only errors.
PJ_LOG_DEBUG
Log errors and additional debug information.
PJ_LOG_TRACE
Highest logging level. Log everything including very detailed debug information.
PJ_LOG_TELL
Special logging level that when used in proj_log_level() will return the current logging level set in
PROJ.
PJ_LOG_FUNC
Function prototype for the logging function used by PROJ. Defined as
typedef void (*PJ_LOG_FUNCTION)(void *, int, const char *);
where the void pointer references a data structure used by the calling application, the int is used to set the
logging level and the const char pointer is the string that will be logged by the function.
9.5.2 Functions
Threading contexts
PJ_CONTEXT* proj_context_create(void)
Create a new threading-context.
9.5. Reference 175

Returns PJ_CONTEXT*
void proj_context_destroy(PJ_CONTEXT *ctx)
Deallocate a threading-context.
Parameters
• ctx (PJ_CONTEXT*) – Threading context.
Transformation setup
PJ* proj_create(PJ_CONTEXT *ctx, const char *definition)

Create a transformation object from a proj-string.
Example call:
PJ *P = proj_create(0, "+proj=etmerc +lat_0=38 +lon_0=125 +ellps=bessel");
The returned PJ-pointer should be deallocated with proj_destroy().

Parameters
• definition (const char*) – Proj-string of the desired transformation.
PJ* proj_create_argv(PJ_CONTEXT *ctx, int argc, char **argv)
Create transformation object with argc/argv-style initialization. For this application each parameter in the defin-
ing proj-string is an entry in argv.
Example call:
char *args[3] = {"proj=utm", "zone=32", "ellps=GRS80"};

PJ* P = proj_create_argv(0, 3, args);

Parameters
• ctx (PJ_CONTEXT*) – Threading context
• argc (int) – Count of arguments in argv
• argv (char**) – Vector of strings with proj-string parameters, e.g. +proj=merc
Returns PJ*
PJ* proj_create_crs_to_crs(PJ_CONTEXT *ctx, const char *srid_from, const char *srid_to,
PJ_AREA *area)
Create a transformation object that is a pipeline between two known coordinate reference systems.
srid_from and srid_to should be the value part of a +init=... parameter set, i.e. “epsg:25833” or
“IGNF:AMST63”. Any projection definition that can be found in a init-file in PROJ_LIB is a valid input to
this function.
For now the function mimics the cs2cs app: An input and an output CRS is given and coordinates are transformed
via a hub datum (WGS84). This transformation strategy is referred to as “early-binding” by the EPSG. The
function can be extended to support “late-binding” transformations in the future without affecting users of the
function. When the function is extended to the late-binding approach the area argument will be used. For now
it is just a place-holder for a future improved implementation.
Example call:

PJ *P = proj_create_crs_to_crs(0, "epsg:25832", "epsg:25833", 0);

Parameters
• srid_from (const char*) – Source SRID.
• srid_to (const char*) – Destination SRID.
• area (PJ_AREA) – Descriptor of the desired area for the transformation.
Returns PJ*
PJ* proj_destroy(PJ *P)
Deallocate a PJ transformation object.
Parameters
• P (PJ*) –
Returns PJ*
Coordinate transformation
PJ_COORD proj_trans(PJ *P, PJ_DIRECTION direction, PJ_COORD coord)

Transform a single PJ_COORD coordinate.
Parameters
• P (PJ*) –
• direction (PJ_DIRECTION) – Transformation direction.
• coord (PJ_COORD) – Coordinate that will be transformed.
Returns PJ_COORD
size_t proj_trans_generic(PJ *P, PJ_DIRECTION direction, double *x, size_t sx, size_t nx, double *y,
size_t sy, size_t ny, double *z, size_t sz, size_t nz, double *t, size_t st,
size_t nt)
Transform a series of coordinates, where the individual coordinate dimension may be represented by an array
that is either
1. fully populated
2. a null pointer and/or a length of zero, which will be treated as a fully populated array of zeroes
3. of length one, i.e. a constant, which will be treated as a fully populated array of that constant value
The strides, sx, sy, sz, st, represent the step length, in bytes, between consecutive elements of the corre-
sponding array. This makes it possible for proj_transform() to handle transformation of a large class of
application specific data structures, without necessarily understanding the data structure format, as in:
typedef struct {
double x, y;
int quality_level;
char surveyor_name[134];
} XYQS;
XYQS survey[345];
9.5. Reference 177


double height = 23.45;
size_t stride = sizeof (XYQS);
...
proj_trans_generic (
P, PJ_INV, sizeof(XYQS),
&(survey[0].x), stride, 345, /* We have 345 eastings */
&(survey[0].y), stride, 345, /* ...and 345 northings. */
&height, 1, /* The height is the constant 23.45 m */
0, 0 /* and the time is the constant 0.00 s */
);
This is similar to the inner workings of the deprecated pj_transform function, but the stride functionality has
been generalized to work for any size of basic unit, not just a fixed number of doubles.
In most cases, the stride will be identical for x, y, z, and t, since they will typically be either individual arrays
(stride = sizeof(double)), or strided views into an array of application specific data structures (stride = sizeof
(. . . )).
But in order to support cases where x, y, z, and t come from heterogeneous sources, individual strides, sx, sy,
sz, st, are used.
Note: Since proj_transform() does its work in place, this means that even the supposedly constants (i.e.
length 1 arrays) will return from the call in altered state. Hence, remember to reinitialize between repeated calls.
Parameters
• P (PJ*) – Transformation object
• direction – Transformation direction
• x (double*) – Array of x-coordinates
• y (double*) – Array of y-coordinates
• z (double*) – Array of z-coordinates
• t (double*) – Array of t-coordinates
• sx (size_t) – Step length, in bytes, between consecutive elements of the corresponding
array
• nx (size_t) – Number of elements in the corresponding array
• sy (size_t) – Step length, in bytes, between consecutive elements of the corresponding
array
• nv (size_t) – Number of elements in the corresponding array
• sz (size_t) – Step length, in bytes, between consecutive elements of the corresponding
array
• nz (size_t) – Number of elements in the corresponding array
• st (size_t) – Step length, in bytes, between consecutive elements of the corresponding
array
• nt (size_t) – Number of elements in the corresponding array
Returns Number of transformations successfully completed

size_t proj_trans_array(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord)

Batch transform an array of PJ_COORD.
Parameters
• P (PJ*) –
• direction (PJ_DIRECTION) – Transformation direction
• n (size_t) – Number of coordinates in coord
Returns size_t 0 if all observations are transformed without error, otherwise returns error number
Error reporting
int proj_errno(PJ *P)

Get a reading of the current error-state of P. An non-zero error codes indicates an error either with the transfor-
mation setup or during a transformation.
Param PJ* P: Transformation object.
Returns int
void proj_errno_set(PJ *P, int err)
Change the error-state of P to err.
param PJ* P Transformation object.
param int err Error number.
int proj_errno_reset(PJ *P)
Clears the error number in P, and bubbles it up to the context.
Example:
void foo (PJ *P) {

int last_errno = proj_errno_reset (P);
do_something_with_P (P);
/* failure - keep latest error status */

if (proj_errno(P))
return;
/* success - restore previous error status */
proj_errno_restore (P, last_errno);
return;
}
Param PJ* P: Transformation object.

Returns int Returns the previous value of the errno, for convenient reset/restore operations.
void proj_errno_restore(PJ *P, int err)

Reduce some mental impedance in the canonical reset/restore use case: Basically, proj_errno_restore()
is a synonym for proj_errno_set(), but the use cases are very different: set indicate an error to higher
level user code, restore passes previously set error indicators in case of no errors at this level.
Hence, although the inner working is identical, we provide both options, to avoid some rather confusing real
world code.
See usage example under proj_errno_reset()
9.5. Reference 179

Parameters
• P (PJ*) – Transformation object.
• err (int) – Error code.
const char* proj_errno_string(int err)
Get a text representation of an error number.
Parameters
• err (int) – Error number.
Returns const char* String with description of error.
Note: Available from version 5.1.0.
Logging
PJ_LOG_LEVEL proj_log_level(PJ_CONTEXT *ctx, PJ_LOG_LEVEL level)

Get and set logging level for a given context. Changes the log level to level and returns the previous log-
ging level. If called with level set to PJ_LOG_TELL the function returns the current logging level without
changing it.
Parameters
• level (PJ_LOG_LEVEL) – New logging level.
Returns PJ_LOG_LEVEL
void proj_log_func(PJ_CONTEXT *ctx, void *app_data, PJ_LOG_FUNCTION logf )
Override the internal log function of PROJ.
Parameters
• app_data (void*) – Pointer to data structure used by the calling application.
• logf (PJ_LOG_FUNCTION ) – Log function that overrides the PROJ log function.
Info functions
PJ_INFO proj_info(void)
Get information about the current instance of the PROJ library.
Returns PJ_INFO
PJ_PROJ_INFO proj_pj_info(const PJ *P)
Get information about a specific transformation object, P.
Parameters
• P (const PJ*) – Transformation object
Returns PJ_PROJ_INFO

PJ_GRID_INFO proj_grid_info(const char *gridname)

Get information about a specific grid.
Parameters
• gridname (const char*) – Gridname in the PROJ searchpath
Returns PJ_GRID_INFO
PJ_INIT_INFO proj_init_info(const char *initname)
Get information about a specific init file.
Parameters
• initname (const char*) – Init file in the PROJ searchpath
Returns PJ_INIT_INFO
Lists
const PJ_OPERATIONS* proj_list_operations(void)

Get a pointer to an array of all operations in PROJ. The last entry of the returned array is a NULL-entry. The
array is statically allocated and does not need to be freed after use.
Print a list of all operations in PROJ:
PJ_OPERATIONS *ops;
for (ops = proj_list_operations(); ops->id; ++ops)
printf("%s\n", ops->id);
Returns PJ_OPERATIONS*
const PJ_ELLPS* proj_list_ellps(void)

Get a pointer to an array of ellipsoids defined in PROJ. The last entry of the returned array is a NULL-entry.
The array is statically allocated and does not need to be freed after use.
Returns PJ_ELLPS*
const PJ_UNITS* proj_list_units(void)
Get a pointer to an array of distance units defined in PROJ. The last entry of the returned array is a NULL-entry.
The array is statically allocated and does not need to be freed after use.
Returns PJ_UNITS*
const PJ_PRIME_MERIDIANS* proj_list_prime_meridians(void)
Get a pointer to an array of prime meridians defined in PROJ. The last entry of the returned array is a NULL-
entry. The array is statically allocated and does not need to be freed after use.
Returns PJ_PRIME_MERIDIANS*
Distances
double proj_lp_dist(const PJ *P, PJ_COORD a, PJ_COORD b)

Calculate geodesic distance between two points in geodetic coordinates. The calculated distance is between the
two points located on the ellipsoid.
Parameters
9.5. Reference 181

• a (PJ_COORD) – Coordinate of first point

• b (PJ_COORD) – Coordinate of second point
Returns double Distance between a and b in meters.
double proj_lpz_dist(const PJ *P, PJ_COORD a, PJ_COORD b)
Calculate geodesic distance between two points in geodetic coordinates. Similar to proj_lp_dist() but
also takes the height above the ellipsoid into account.
Parameters
• a (PJ_COORD) – Coordinate of first point
• b (PJ_COORD) – Coordinate of second point
double proj_xy_dist(PJ_COORD a, PJ_COORD b)
Calculate 2-dimensional euclidean between two projected coordinates.
Parameters
• a (PJ_COORD) – First coordinate
• b (PJ_COORD) – Second coordinate
double proj_xyz_dist(PJ_COORD a, PJ_COORD b)
Calculate 3-dimensional euclidean between two projected coordinates.
Parameters
• a (PJ_COORD) – First coordinate
• b (PJ_COORD) – Second coordinate
Various
PJ_COORD proj_coord(double x, double y, double z, double t)

Initializer for the PJ_COORD union. The function is shorthand for the otherwise convoluted assignment. Equiv-
alent to
PJ_COORD c = {{10.0, 20.0, 30.0, 40.0}};
or
PJ_COORD c;
// Assign using the PJ_XYZT struct in the union
c.xyzt.x = 10.0;
c.xyzt.y = 20.0;
c.xyzt.z = 30.0;
c.xyzt.t = 40.0;
Since PJ_COORD is a union of structs, the above assignment can also be expressed in terms of the other types
in the union, e.g. PJ_UVWT or PJ_LPZT.
Parameters

• x (double) – 1st component in a PJ_COORD

• y (double) – 2nd component in a PJ_COORD
• z (double) – 3rd component in a PJ_COORD
• t (double) – 4th component in a PJ_COORD
Returns PJ_COORD
double proj_roundtrip(PJ *P, PJ_DIRECTION direction, int n, PJ_COORD *coord)
Measure internal consistency of a given transformation. The function performs n round trip transformations
starting in either the forward or reverse direction. Returns the euclidean distance of the starting point coo
and the resulting coordinate after n iterations back and forth.
Parameters
• P (const PJ*) –
• direction (PJ_DIRECTION) – Starting direction of transformation
• n (int) – Number of roundtrip transformations
• coord (PJ_COORD) – Input coordinate
Returns double Distance between original coordinate and the resulting coordinate after n trans-
formation iterations.
PJ_FACTORS proj_factors(PJ *P, PJ_COORD lp)
Calculate various cartographic properties, such as scale factors, angular distortion and meridian convergence.
Depending on the underlying projection values will be calculated either numerically (default) or analytically.
The function also calculates the partial derivatives of the given coordinate.
Parameters
• lp (const PJ_COORD) – Geodetic coordinate
Returns PJ_FACTORS
double proj_torad(double angle_in_degrees)
Convert degrees to radians.
Parameters
• angle_in_degrees (double) – Degrees
Returns double Radians
double proj_todeg(double angle_in_radians)
Convert radians to degrees
Parameters
• angle_in_radians (double) – Radians
Returns double Degrees
double proj_dmstor(const char *is, char **rs)
Convert string of degrees, minutes and seconds to radians. Works similarly to the C standard library function
strtod().
Parameters
• is (const char*) – Value to be converted to radians
9.5. Reference 183

• rs – Reference to an already allocated char*, whose value is set by the function to the next
character in is after the numerical value.
char *proj_rtodms(char *s, double r, int pos, int neg)
Convert radians to string representation of degrees, minutes and seconds.
Parameters
• s (char*) – Buffer that holds the output string
• r (double) – Value to convert to dms-representation
• pos (int) – Character denoting positive direction, typically ‘N’ or ‘E’.
• neg (int) – Character denoting negative direction, typically ‘S’ or ‘W’.
Returns char* Pointer to output buffer (same as s)
PJ_COORD proj_geocentric_latitude(const PJ *P, PJ_DIRECTION direction, PJ_COORD co-
ord)
Convert from geographical latitude to geocentric latitude.
Parameters
• coord (PJ_COORD) – Coordinate
Returns PJ_COORD Converted coordinate
int proj_angular_input(PJ *P, enum PJ_DIRECTION dir)
Check if a operation expects angular input.
Parameters
Returns int 1 if angular input is expected, otherwise 0
int proj_angular_output(PJ *P, enum PJ_DIRECTION dir)
Check if an operation returns angular output.
param P Transformation object
type P const PJ*
param direction Starting direction of transformation
type direction PJ_DIRECTION
returns int 1 if angular output is returned, otherwise 0
9.5.3 Deprecated API
Contents
• Deprecated API
– Introduction
– Example

– API Functions
* pj_transform
* pj_init_plus
* pj_free
* pj_is_latlong
* pj_is_geocent
* pj_get_def
* pj_latlong_from_proj
* pj_set_finder
* pj_set_searchpath
* pj_deallocate_grids
* pj_strerrno
* pj_get_errno_ref
* pj_get_release
Introduction
Procedure pj_init() selects and initializes a cartographic projection with its argument control parameters. argc is
the number of elements in the array of control strings argv that each contain individual cartographic control keyword
assignments (+ proj arguments). The list must contain at least the proj=projection and Earth’s radius or elliptical
parameters. If the initialization of the projection is successful a valid address is returned otherwise a NULL value.
The pj_init_plus() function operates similarly to pj_init() but takes a single string containing the definition,
with each parameter prefixed with a plus sign. For example +proj=utm +zone=11 +ellps=WGS84.
Once initialization is performed either forward or inverse projections can be performed with the returned value of
pj_init() used as the argument proj. The argument structure projUV values u and v contain respective longitude
and latitude or x and y. Latitude and longitude are in radians. If a projection operation fails, both elements of projUV
are set to HUGE_VAL (defined in math.h).
Note: all projections have a forward mode, but some do not have an inverse projection. If the projection does not have
an inverse the projPJ structure element inv will be NULL.
The pj_transform function may be used to transform points between the two provided coordinate systems. In
addition to converting between cartographic projection coordinates and geographic coordinates, this function also
takes care of datum shifts if possible between the source and destination coordinate system. Unlike pj_fwd()
and pj_inv() it is also allowable for the coordinate system definitions (projPJ *) to be geographic coordinate
systems (defined as +proj=latlong). The x, y and z arrays contain the input values of the points, and are replaced
with the output values. The function returns zero on success, or the error number (also in pj_errno) on failure.
Memory associated with the projection may be freed with pj_free().
Example
The following program reads latitude and longitude values in decimal degrees, performs Mercator projection with a
Clarke 1866 ellipsoid and a 33° latitude of true scale and prints the projected cartesian values in meters:
9.5. Reference 185

#include <proj_api.h>
main(int argc, char **argv) {

projPJ pj_merc, pj_latlong;
double x, y;
if (!(pj_merc = pj_init_plus("+proj=merc +ellps=clrk66 +lat_ts=33")) )

exit(1);
if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) )
exit(1);
while (scanf("%lf %lf", &x, &y) == 2) {
x *= DEG_TO_RAD;
y *= DEG_TO_RAD;
p = pj_transform(pj_latlong, pj_merc, 1, 1, &x, &y, NULL );
printf("%.2f\t%.2f\n", x, y);
}
exit(0);
}
For this program, an input of -16 20.25 would give a result of -1495284.21 1920596.79.
API Functions
pj_transform
int pj_transform( projPJ srcdefn,

projPJ dstdefn,
long point_count,
int point_offset,
double *x,
double *y,
double *z );
Transform the x/y/z points from the source coordinate system to the destination coordinate system.
srcdefn: source (input) coordinate system.
dstdefn: destination (output) coordinate system.
point_count: the number of points to be processed (the size of the x/y/z arrays).
point_offset: the step size from value to value (measured in doubles) within the x/y/z arrays - normally 1 for a
packed array. May be used to operate on xyz interleaved point arrays.
x/y/z: The array of X, Y and Z coordinate values passed as input, and modified in place for output. The Z may
optionally be NULL.
return: The return is zero on success, or a PROJ.4 error code.
The pj_transform() function transforms the passed in list of points from the source coordinate system to the
destination coordinate system. Note that geographic locations need to be passed in radians, not decimal degrees, and
will be returned similarly. The z array may be passed as NULL if Z values are not available.
If there is an overall failure, an error code will be returned from the function. If individual points fail to transform -
for instance due to being over the horizon - then those x/y/z values will be set to HUGE_VAL on return. Input values
that are HUGE_VAL will not be transformed.

pj_init_plus
projPJ pj_init_plus(const char *definition);
This function converts a string representation of a coordinate system definition into a projPJ object suitable for use
with other API functions. On failure the function will return NULL and set pj_errno. The definition should be of
the general form +proj=tmerc +lon_0 +datum=WGS84. Refer to PROJ.4 documentation and the Geodetic
transformation notes for additional detail.
Coordinate system objects allocated with pj_init_plus() should be deallocated with pj_free().
pj_free
void pj_free( projPJ pj );
Frees all resources associated with pj.
pj_is_latlong
int pj_is_latlong( projPJ pj );
Returns TRUE if the passed coordinate system is geographic (proj=latlong).
pj_is_geocent
int pj_is_geocent( projPJ pj );``
Returns TRUE if the coordinate system is geocentric (proj=geocent).
pj_get_def
char *pj_get_def( projPJ pj, int options);``
Returns the PROJ.4 initialization string suitable for use with pj_init_plus() that would produce this coordinate
system, but with the definition expanded as much as possible (for instance +init= and +datum= definitions).
pj_latlong_from_proj
projPJ pj_latlong_from_proj( projPJ pj_in );``
Returns a new coordinate system definition which is the geographic coordinate (lat/long) system underlying pj_in.
pj_set_finder
void pj_set_finder( const char *(*new_finder)(const char *) );``
Install a custom function for finding init and grid shift files.
9.5. Reference 187

pj_set_searchpath
void pj_set_searchpath ( int count, const char **path );``
Set a list of directories to search for init and grid shift files.
pj_deallocate_grids
void pj_deallocate_grids( void );``
Frees all resources associated with loaded and cached datum shift grids.
pj_strerrno
char *pj_strerrno( int );``
Returns the error text associated with the passed in error code.
pj_get_errno_ref
int *pj_get_errno_ref( void );``
Returns a pointer to the global pj_errno error variable.
pj_get_release
const char *pj_get_release( void );``
Returns an internal string describing the release version.
Obsolete Functions
XY pj_fwd( LP lp, PJ *P );
LP pj_inv( XY xy, PJ *P );
projPJ pj_init(int argc, char **argv);
9.6 Using PROJ in CMake projects
The recommended way to use the PROJ library in a CMake project is to link to the imported library target
${PROJ4_LIBRARIES} provided by the CMake configuration which comes with the library. Typical usage is:
find_package(PROJ4)
target_link_libraries(MyApp ${PROJ4_LIBRARIES})

By adding the imported library target ${PROJ4_LIBRARIES} to the target link libraries, CMake will also pass the
include directories to the compiler. This requires that you use CMake version 2.8.11 or later. If you are using an older
version of CMake, then add
include_directories(${PROJ4_INCLUDE_DIRS})
The CMake command find_package will look for the configuration in a number of places. The lookup can be
adjusted for all packages by setting the cache variable or environment variable CMAKE_PREFIX_PATH. In particular,
CMake will consult (and set) the cache variable PROJ4_DIR.
9.7 Language bindings
PROJ bindings are available for a number of different development platforms.
9.7.1 Python
pyproj: Python interface (wrapper for PROJ)
9.7.2 Ruby
proj4rb: Bindings for PROJ in ruby
9.7.3 TCL
proj4tcl: Bindings for PROJ in tcl (critcl source)
9.7.4 MySQL
fProj4: Bindings for PROJ in MySQL
9.7.5 Excel
proj.xll: Excel add-in for PROJ map projections
9.7.6 Visual Basic
PROJ VB Wrappers: By Eric G. Miller.
9.8 Version 4 to 5 API Migration
This is a transition guide for developers wanting to migrate their code to use PROJ version 5.
9.7. Language bindings 189

9.8.1 Background
Before we go on, a bit of background is needed. The new API takes a different view of the world than the old because
it is needed in order to obtain high accuracy transformations. The old API is constructed in such a way that any
transformation between two coordinate reference systems must pass through the ill-defined WGS84 reference frame,
using it as a hub. The new API does away with this limitation to transformations in PROJ. It is still possible to do that
type of transformations but in many cases there will be a better alternative.
The world view represented by the old API is always sufficient if all you care about is meter level accuracy - and in
many cases it will provide much higher accuracy than that. But the view that “WGS84 is the true foundation of the
world, and everything else can be transformed natively to and from WGS84” is inherently flawed.
First and foremost because any time WGS84 is mentioned, you should ask yourself “Which of the six WGS84 real-
izations are we talking about here?”.
Second, because for many (especially legacy) systems, it may not be straightforward to transform to WGS84 (or
actually ITRF-something, ETRS-something or NAD-something which appear to be the practical meaning of the term
WGS84 in everyday PROJ related work), while centimeter-level accurate transformations may exist between pairs of
older systems.
The concept of a hub reference frame (“datum”) is not inherently bad, but in many cases you need to handle and select
that datum with more care than the old API allows. The primary aim of the new API is to allow just that. And to
do that, you must realize that the world is inherently 4 dimensional. You may in many cases assume one or more
of the coordinates to be constant, but basically, to obtain geodetic accuracy transformations, you need to work in 4
dimensions.
Now, having described the background for introducing the new API, let’s try to show how to use it. First note that
in order to go from system A to system B, the old API starts by doing an inverse transformation from system A to
WGS84, then does a forward transformation from WGS84 to system B.
With cs2cs being the command line interface to the old API, and cct being the same for the new, this example of
doing the same thing in both world views will should give an idea of the differences:
$ echo 300000 6100000 | cs2cs +proj=utm +zone=33 +ellps=GRS80 +to +proj=utm +zone=32
˓→+ellps=GRS80
683687.87 6099299.66 0.00
$ echo 300000 6100000 0 0 | cct +proj=pipeline +step +inv +proj=utm +zone=33

˓→+ellps=GRS80 +step +proj=utm +zone=32 +ellps=GRS80
683687.8667 6099299.6624 0.0000 0.0000
Lookout for the +inv in the first +step, indicating an inverse transform.
9.8.2 Code example
The difference between the old and new API is shown here with a few examples. Below we implement the same
program with the two different API’s. The program reads input latitude and longitude from the command line and
convert them to projected coordinates with the Mercator projection.
We start by writing the program for PROJ v. 4:
#include <proj_api.h>

projPJ pj_merc, pj_latlong;
double x, y;

if (!(pj_merc = pj_init_plus("+proj=merc +ellps=clrk66 +lat_ts=33")) )

return 1;
if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) )
return 1;
while (scanf("%lf %lf", &x, &y) == 2) {

x *= DEG_TO_RAD;
y *= DEG_TO_RAD;
p = pj_transform(pj_latlong, pj_merc, 1, 1, &x, &y, NULL );
printf("%.2f\t%.2f\n", x, y);
}
return 0;
}
The same program implemented using PROJ v. 5:
#include <proj.h>

PJ *P;
PJ_COORD c;
P = proj_create(PJ_DEFAULT_CTX, "+proj=merc +ellps=clrk66 +lat_ts=33");

if (P==0)
return 1;
while (scanf("%lf %lf", &c.lp.lam, &c.lp.phi) == 2) {

c.lp.lam = proj_todeg(c.lp.lam);
c.lp.phi = proj_todeg(c.lp.phi);
c = proj_trans(P, PJ_FWD, c);
printf("%.2f\t%.2f\n", c.xy.x, c.xy.y);
}
Looking at the two different programs, there’s a few immediate differences that catches the eye. First off, the included
header file describing the API has changed from proj_api.h to simply proj.h. All functions in proj.h belongs
to the proj_ namespace.
With the new API also comes new datatypes. E.g. the transformation object projPJ which has been changed to a
pointer of type PJ. This is done to highlight the actual nature of the object, instead of hiding it away behind a typedef.
New data types for handling coordinates have also been introduced. In the above example we use the PJ_COORD,
which is a union of various types. The benefit of this is that it is possible to use the various structs in the union to
communicate what state the data is in at different points in the program. For instance as in the above example where
the coordinate is read from STDIN as a geodetic coordinate, communicated to the reader of the code by using the
c.lp struct. After it has been projected we print it to STDOUT by accessing the individual elements in c.xy to
illustrate that the coordinate is now in projected space. Data types are prefixed with PJ_.
The final, and perhaps biggest, change is that the fundamental concept of transformations in PROJ are now handled
in a single transformation object (PJ) and not by stating the source and destination systems as previously. It is
of course still possible to do just that, but the transformation object now captures the whole transformation from
source to destination in one. In the example with the old API the source system is described as +proj=latlon
+ellps=clrk66 and the destination system is described as +proj=merc +ellps=clrk66 +lat_ts=33.
Since the Mercator projection accepts geodetic coordinates as its input, the description of the source in this case is
superfluous. We use that to our advantage in the new API and simply state the destination. This is simple at a glance,
9.8. Version 4 to 5 API Migration 191

but is actually a big conceptual change. We are now focused on the path between two systems instead of what the
source and destination systems are.
9.8.3 Function mapping from old to new API
Old API functions New API functions

pj_fwd proj_trans
pj_inv proj_trans
pj_fwd3 proj_trans
pj_inv3 proj_trans
pj_transform proj_trans_array or proj_trans_generic
pj_init proj_create
pj_init_plus proj_create
pj_free proj_destroy
pj_is_latlong proj_angular_output
pj_is_geocent proj_angular_outout
pj_get_def proj_pj_info
pj_latlong_from_proj No equivalent
pj_set_finder No equivalent
pj_set_searchpath No equivalent
pj_deallocate_grids No equivalent
pj_strerrno No equivalent
pj_get_errno_ref proj_errno
pj_get_release proj_info

CHAPTER
TEN
COMMUNITY
The PROJ community is what makes the software stand out from its competitors. PROJ is used and developed by group
of very enthusiastic, knowledgeable and friendly people. Whether you are a first time user of PROJ or a long-time
contributor the community is always very welcoming.
10.1 Communication channels
10.1.1 Mailing list
Users and developers of the library are using the mailing list to discuss all things related to PROJ. The mailing list is
the primary forum for asking for help with use of PROJ. The mailing list is also used for announcements, discussions
about the development of the library and from time to time interesting discussions on geodesy appear as well. You are
more than welcome to join in on the discussions!
The PROJ mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj
10.1.2 GitHub
GitHub is the development platform we use for collaborating on the PROJ code. We use GitHub to keep track of the
changes in the code and to index bug reports and feature requests. We are happy to take contributions in any form,
either as code, bug reports, documentation or feature requests. See Contributing for more info on how you can help
improve PROJ.
The PROJ GitHub page can be found at https://github.com/OSGeo/proj.4
Note: The issue tracker on GitHub is only meant to keep track of bugs, feature request and other things related to the
development of PROJ. Please ask your questions about the use of PROJ on the mailing list instead.
10.2 Contributing
PROJ has a wide and varied user base. Some are highly skilled geodesists with a deep knowledge of map projections
and reference systems, some are GIS software developers and others are GIS users. All users, regardless of the
profession or skill level, has the ability to contribute to PROJ. Here’s a few suggestion on how:
• Help PROJ-users that is less experienced than yourself.
• Write a bug report
• Request a new feature
193
• Write documentation for your favorite map projection

• Fix a bug
• Implement a new feature
In the following sections you can find some guidelines on how to contribute. As PROJ is managed on GitHub most
contributions require that you have a GitHub account. Familiarity with issues and the GitHub Flow is an advantage.
10.2.1 Help a fellow PROJ user
The main forum for support for PROJ is the mailing list. You can subscribe to the mailing list here and read the archive
here.
If you have questions about the usage of PROJ the mailing list is also the place to go. Please do not use the GitHub
issue tracker as a support forum. Your question is much more likely to be answered on the mailing list, as many more
people follow that than the issue tracker.
10.2.2 Adding bug reports
Bug reports are handled in the issue tracker on PROJ’s home on GitHub. Writing a good bug report is not easy. But
fixing a poorly documented bug is not easy either, so please put in the effort it takes to create a thorough bug report.
A good bug report includes at least:
• A title that quickly explains the problem
• A description of the problem and how it can be reproduced
• Version of PROJ being used
• Version numbers of any other relevant software being used, e.g. operating system
• A description of what already has been done to solve the problem
The more information that is given up front, the more likely it is that a developer will find interest in solving the
problem. You will probably get follow-up questions after submitting a bug report. Please answer them in a timely
manner if you have an interest in getting the issue solved.
Finally, please only submit bug reports that are actually related to PROJ. If the issue materializes in software that uses
PROJ it is likely a problem with that particular software. Make sure that it actually is a PROJ problem before you
submit an issue. If you can reproduce the problem only by using tools from PROJ it is definitely a problem with PROJ.
10.2.3 Feature requests
Got an idea for a new feature in PROJ? Submit a thorough description of the new feature in the issue tracker. Please
include any technical documents that can help the developer make the new feature a reality. An example of this could
be a publicly available academic paper that describes a new projection. Also, including a numerical test case will make
it much easier to verify that an implementation of your requested feature actually works as you expect.
Note that not all feature requests are accepted.
10.2.4 Write documentation
PROJ is in dire need of better documentation. Any contributions of documentation are greatly appreciated. The PROJ
documentation is available on proj4.org. The website is generated with Sphinx. Contributions to the documentation
should be made as Pull Requests on GitHub.
194 Chapter 10. Community

If you intend to document one of PROJ’s supported projections please use the Mercator projection as a template.
10.2.5 Code contributions
See Code contributions
Legalese
Committers are the front line gatekeepers to keep the code base clear of improperly contributed code. It is important
to the PROJ users, developers and the OSGeo foundation to avoid contributing any code to the project without it being
clearly licensed under the project license.
Generally speaking the key issues are that those providing code to be included in the repository understand that the
code will be released under the MIT/X license, and that the person providing the code has the right to contribute the
code. For the committer themselves understanding about the license is hopefully clear. For other contributors, the
committer should verify the understanding unless the committer is very comfortable that the contributor understands
the license (for instance frequent contributors).
If the contribution was developed on behalf of an employer (on work time, as part of a work project, etc) then it is
important that an appropriate representative of the employer understand that the code will be contributed under the
MIT/X license. The arrangement should be cleared with an authorized supervisor/manager, etc.
The code should be developed by the contributor, or the code should be from a source which can be rightfully con-
tributed such as from the public domain, or from an open source project under a compatible license.
All unusual situations need to be discussed and/or documented.
Committers should adhere to the following guidelines, and may be personally legally liable for improperly contributing
code to the source repository:
• Make sure the contributor (and possibly employer) is aware of the contribution terms.
• Code coming from a source other than the contributor (such as adapted from another project) should be clearly
marked as to the original source, copyright holders, license terms and so forth. This information can be in the file
headers, but should also be added to the project licensing file if not exactly matching normal project licensing
(COPYING).
• Existing copyright headers and license text should never be stripped from a file. If a copyright holder wishes
to give up copyright they must do so in writing to the foundation before copyright messages are removed. If
license terms are changed it has to be by agreement (written in email is ok) of the copyright holders.
• Code with licenses requiring credit, or disclosure to users should be added to COPYING.
• When substantial contributions are added to a file (such as substantial patches) the author/contributor should be
added to the list of copyright holders for the file.
• If there is uncertainty about whether a change is proper to contribute to the code base, please seek more infor-
mation from the project steering committee, or the foundation legal counsel.
10.2.6 Additional Resources
• General GitHub documentation

• GitHub pull request documentation
10.2. Contributing 195

10.2.7 Acknowledgements
The code contribution section of this CONTRIBUTING file is inspired by PDAL’s and the legalese section is modified
from GDAL committer guidelines
10.3 Guidelines for PROJ code contributors
This is a guide for PROJ, casual or regular, code contributors.
10.3.1 Code contributions.
Code contributions can be either bug fixes or new features. The process is the same for both, so they will be discussed
together in this section.
Making Changes
• Create a topic branch from where you want to base your work.
• You usually should base your topic branch off of the master branch.
• To quickly create a topic branch: git checkout -b my-topic-branch
• Make commits of logical units.
• Check for unnecessary whitespace with git diff --check before committing.
• Make sure your commit messages are in the proper format.
• Make sure you have added the necessary tests for your changes.
• Make sure that all tests pass
Submitting Changes
• Push your changes to a topic branch in your fork of the repository.

• Submit a pull request to the PROJ repository in the OSGeo organization.
• If your pull request fixes/references an issue, include that issue number in the pull request. For example:
Wiz the bang
Fixes #123.
• PROJ developers will look at your patch and take an appropriate action.
Coding conventions
Programming language
PROJ is developed strictly in ANSI C 89.

Coding style
We don’t enforce any particular coding style, but please try to keep it as simple as possible. If improving existing
code, please try to conform with the style of the locally surrounding code.
Whitespace
Throughout the PROJ code base you will see differing whitespace use. The general rule is to keep whitespace in
whatever form it is in the file you are currently editing. If the file has a mix of tabs and space please convert the tabs
to space in a separate commit before making any other changes. This makes it a lot easier to see the changes in diffs
when evaluating the changed code. New files should use spaces as whitespace.
File names
Files in which projections are implemented are prefixed with an upper-case PJ_ and most other files are prefixed with
lower-case pj_. Some file deviate from this pattern, most of them dates back to the very early releases of PROJ. New
contributions should follow the pj-prefix pattern. Unless there are obvious reasons not to.
10.3.2 Tools
cppcheck static analyzer
You can run locally scripts/cppcheck.sh that is a wrapper script around the cppcheck utility. It is known
to work with cppcheck 1.61 of Ubuntu Trusty 14.0, since this is what is currently used on Travis-CI (travis/
linux_gcc/before_install.sh). At the time of writing, this also works with cppcheck 1.72 of Ubuntu Xenial
16.04, and latest cppcheck master.
cppcheck can have false positives. In general, it is preferable to rework the code a bit to make it more ‘obvious’ and
avoid those false positives. When not possible, you can add a comment in the code like
/* cppcheck-suppress duplicateBreak */
in the preceding line. Replace duplicateBreak with the actual name of the violated rule emitted by cppcheck.
CLang Static Analyzer (CSA)
CSA is run by the travis/csa build configuration. You may also run it locally.
Preliminary step: install clang. For example:
wget http://releases.llvm.org/6.0.0/clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04.
˓→tar.xz
tar xJf clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04.tar.xz
Run configure under the scan-build utility of clang:
./clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04/bin/scan-build ./configure
Build under scan-build:
./clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04/bin/scan-build make [-j8]
10.3. Guidelines for PROJ code contributors 197

If CSA finds errors, they will be emitted during the build. And in which case, at the end of the build process, scan-
build will emit a warning message indicating errors have been found and how to display the error report. This is with
someling like
./clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04/bin/scan-view /tmp/scan-build-2018-
˓→03-15-121416-17476-1
This will open a web browser with the interactive report.

CSA may also have false positives. In general, this happens when the code is non-trivial / makes assumptions that hard
to check at first sight. You will need to add extra checks or rework it a bit to make it more “obvious” for CSA. This
will also help humans reading your code !
Typo detection and fixes
Run scripts/fix_typos.sh
Include What You Use (IWYU)
Managing C includes is a pain. IWYU makes updating headers a bit easier. IWYU scans the code for functions
that are called and makes sure that the headers for all those functions are present and in sorted order. However, you
cannot blindly apply IWYU to PROJ. It does not understand ifdefs, other platforms, or the order requirements of PROJ
internal headers. So the way to use it is to run it on a copy of the source and merge in only the changes that make
sense. Additions of standard headers should always be safe to merge. The rest require careful evaluation. See the
IWYU documentation for motivation and details.
IWYU docs

CHAPTER
ELEVEN
FAQ
11.1 Where can I find the list of projections and their arguments?
There is no simple single location to find all the required information. The !PostScript/PDF documents listed on the
[http://trac.osgeo.org/proj/wiki main] PROJ page under documentation are the authoritative source but projections and
options are spread over several documents in a form more related to their order of implementation than anything else.
The ‘’‘proj’‘’ command itself can report the list of projections using the ‘’‘-lp’‘’ option, the list of ellipsoids with the
‘’‘-le’‘’ option, the list of units with the ‘’‘-lu’‘’ option, and the list of built-in datums with the ‘’‘-ld’‘’ option.
The [http://www.remotesensing.org/geotiff/proj_list/ GeoTIFF Projections Pages] include most of the common PROJ
projections, and a definition of the projection specific options for each.
• How do I do datum shifts between NAD27 and NAD83?
While the ‘’‘nad2nad’‘’ program can be used in some cases, the ‘’‘cs2cs’‘’ is now the preferred mechanism. The
following example demonstrates using the default shift parameters for NAD27 to NAD83:
% cs2cs +proj=latlong +datum=NAD27 +to +proj=latlong +datum=NAD83 -117 30
producing:
117d0'2.901"W 30d0'0.407"N 0.000
In order for datum shifting to work properly the various grid shift files must be available. See below. More details are
available in the [wiki:GenParms#nadgrids-GridBasedDatumAdjustments General Parameters] document.
11.2 How do I build/configure PROJ to support datum shifting?
After downloading and unpacking the PROJ source, also download and unpack the set of datum shift files. See
Download for instructions how to fetch and install these files
On Windows the extra nadshift target must be used. For instance nmake /f makefile.vc nadshift in the
proj/src directory.
A default build and install on Unix will normally build knowledge of the directory where the grid shift files are
installed into the PROJ library (usually /usr/local/share/proj). On Windows the library is normally built thinking that
C:PROJNAD is the installed directory for the grid shift files. If the built in concept of the PROJ data directory is
incorrect, the PROJ_LIB environment can be defined with the correct directory.
199
11.3 How do I debug problems with NAD27/NAD83 datum shifting?
1. Verify that you have the binary files (eg. /usr/local/share/proj/conus) installed on your system. If not, see the
previous question.
2. Try a datum shifting operation in relative isolation, such as with the cs2cs command listed above. Do you
get reasonable results? If not it is likely the grid shift files aren’t being found. Perhaps you need to define
PROJ_LIB?
3. The cs2cs command and the underlying pj_transform() API know how to do a grid shift as part of a more
complex coordinate transformation; however, it is imperative that both the source and destination coordinate
system be defined with appropriate datum information. That means that implicitly or explicitly there must
be a +datum= clause, a +nadgrids= clause or a +towgs84= clause. For instance cs2cs +proj=latlong
+datum=NAD27 +to +proj=latlong +ellps=WGS84 won’t work because defining the output coor-
dinate system as using the ellipse WGS84 isn’t the same as defining it to use the datum WGS84 (use +da-
tum=WGS84). If either the input or output are not identified as having a datum, the datum shifting (and ellipsoid
change) step is just quietly skipped!
4. The PROJ_DEBUG environment can be defined (any value) to force extra output from the PROJ library to stderr
(the text console normally) with information on what data files are being opened and in some cases why a
transformation fails.
export PROJ_DEBUG=ON
cs2cs ...
Note: PROJ_DEBUG support is not yet very mature in the PROJ library.
5. The -v flag to cs2cs can be useful in establishing more detail on what parameters being used internally for a
coordinate system. This will include expanding the definition of +datum clause.
11.4 How do I use EPSG coordinate system codes with PROJ?
There is somewhat imperfect translation between 2d geographic and projected coordinate system codes and PROJ
descriptions of the coordinate system available in the epsg definition file that normally lives in the proj/nad directory.
If installed (it is installed by default on Unix), it is possible to use EPSG numbers like this:
% cs2cs -v +init=epsg:26711
# ---- From Coordinate System ----
#Universal Transverse Mercator (UTM)
# Cyl, Sph
# zone= south
# +init=epsg:26711 +proj=utm +zone=11 +ellps=clrk66 +datum=NAD27 +units=m
# +no_defs +nadgrids=conus,ntv1_can.dat
#--- following specified but NOT used
# +ellps=clrk66
# ---- To Coordinate System ----
#Lat/long (Geodetic)
#
# +proj=latlong +datum=NAD27 +ellps=clrk66 +nadgrids=conus,ntv1_can.dat
The proj/nad/epsg file can be browsed and searched in a text editor for coordinate systems. There are known to be
problems with some coordinate systems, and any coordinate systems with odd axes, a non-greenwich prime meridian
or other quirkiness are unlikely to work properly. Caveat Emptor!
200 Chapter 11. FAQ

11.5 How do I use 3 parameter and 7 parameter datum shifting
Datum shifts can be approximated with 3 and 7 parameter transformations. Their use is more fully described in the
[wiki:GenParms#towgs84-DatumtransformationtoWGS84 towgs84] parameter discussion.
11.6 Does PROJ work in different international numeric locales?
No. PROJ makes extensive use of sprintf() and atof() internally to translate numeric values. If a locale is in effect that
modifies formatting of numbers, altering the role of commas and periods in numbers, then PROJ will not work. This
problem is common in some European locales.
On unix-like platforms, this problem can be avoided by forcing the use of the default numeric locale by setting the
LC_NUMERIC environment variable to C.
$ export LC_NUMERIC=C
$ proj ...
Note: NOTE: Per ticket #49, in PROJ 4.7.0 and later pj_init() operates with locale overridden to “C” to avoid most
locale specific processing for applications using the API. Command line tools may still have issues.
11.7 Changing Ellipsoid / Why can’t I convert from WGS84 to Google

Earth / Virtual Globe Mercator?
The coordinate system definition for Google Earth, and Virtual Globe Mercator is as follows, which uses a sphere as
the earth model for the Mercator projection.
+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0

+x_0=0.0 +y_0=0 +k=1.0 +units=m +no_defs
But, if you do something like:
cs2cs +proj=latlong +datum=WGS84

+to +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0
+x_0=0.0 +y_0=0 +k=1.0 +units=m +no_defs
to convert between WGS84 and mercator on the sphere there will be substantial shifts in the Y mercator coordinates.
This is because internally cs2cs is having to adjust the lat/long coordinates from being on the sphere to being on the
WGS84 datum which has a quite differently shaped ellipsoid.
In this case, and many other cases using spherical projections, the desired approach is to actually treat the lat/long
locations on the sphere as if they were on WGS84 without any adjustments when using them for converting to other
coordinate systems. The solution is to “trick” PROJ into applying no change to the lat/long values when going to
(and through) WGS84. This can be accomplished by asking PROJ to use a null grid shift file for switching from your
spherical lat/long coordinates to WGS84.
cs2cs +proj=latlong +datum=WGS84 \

+to +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 \
+x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +no_defs
11.5. How do I use 3 parameter and 7 parameter datum shifting 201

Note the strategic addition of +nadgrids=@null to the spherical projection definition.

Similar issues apply with many other datasets distributed with projections based on a spherical earth model - such
as many NASA datasets. This coordinate system is now known by the EPSG code 3857 and has in the past been
known as EPSG:3785 and EPSG:900913. When using this coordinate system with GDAL/OGR it is helpful to include
the +wktext so the exact PROJ string will be preserved in the WKT representation (otherwise key parameters like
+nadgrids=@null will be dropped):
+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0

+units=m +nadgrids=@null +wktext +no_defs
11.8 Why do I get different results with 4.5.0 and 4.6.0?
The default datum application behavior changed with the 4.6.0 release. PROJ will now only apply a datum shift if
both the source and destination coordinate system have valid datum shift information.
From the PROJ 4.6.0 Release Notes (in NEWS):
• MAJOR: Rework pj_transform() to avoid applying ellipsoid to ellipsoid transformations as a datum shift
when no datum info is available.
11.9 How do I calculate distances/directions on the surface of the

earth?
These are called geodesic calculations. There is a page about it here: Geodesic calculations.
11.10 What is the HEALPix projection and how can I use it?
The HEALPix projection is area

preserving and can be used
with a spherical and ellipsoidal
model. It was initially de-
veloped for mapping cosmic
background microwave radia-
tion. The image below is
the graphical representation of
the mapping and consists of
eight isomorphic triangular in-
terrupted map graticules. The
north and south contains four
in which straight meridians con-
verge polewards to a point
and unequally spaced horizon-
tal parallels. HEALPix pro-
vides a mapping in which points
of equal latitude and equally
spaced longitude are mapped
to points of equal latitude and
equally spaced longitude with
202 Chapter 11. FAQ

the module of the polar inter-

ruptions. ||
To run a forward HEALPix projection on a unit sphere model, use the following command:
proj +proj=healpix +lon_0=0 +a=1 -E <<EOF

0 0
EOF
Output of the above command.
0 0 0.00 0.00
11.11 What is the rHEALPix projection and how can I use it?
rHEALPix is a projection based

on the HEALPix projection. The
implementation of rHEALPix
uses the HEALPix projection.
The rHEALPix combines the
peaks of the HEALPix into a
square. The square’s position
can be translated and rotated
across the x-axis which is a novel
approach for the rHEALPix pro-
jection. The initial intention
of using rHEALPix in the Spa-
tial Computation Engine Sci-
ence Collaboration Environment
(SCENZGrid).
To run a inverse rHEALPix pro-
jection on a WGS84 ellipsoidal
model, use the following command:
proj +proj=rhealpix -f '%.2f' -I +lon_0=0 +a=1 +ellps=WGS84 +npole=0 +spole=0 -E <<EOF

0 0.7853981633974483
EOF
Where spole and npole are integers from the range of 0 to 3 inclusive and represent the positions of the north polar
and south polar squares.
Output of above command:
0 0.7853981633974483 0.00 41.94
11.12 What options does PROJ allow for the shape of the Earth
(geodesy)?
See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c for possible ellipse options. For example, putting

+ellps=WGS84 uses the WGS84 Earth shape.
11.11. What is the rHEALPix projection and how can I use it? 203
11.13 What if I want a spherical Earth?
Use +ellps=sphere. See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c for the radius used in this

case.
11.14 How do I change the radius of the Earth? How do I use PROJ
for work on Mars?
You can supply explicit values for the semi minor and semi major axes instead of using the symbolic “sphere” value.
Eg, if the radius were 2000000m:
+proj=laea +lon_0=-40.000000 +lat_0=74.000000 +x_0=1000000 +y_0=1700000 +a=2000000

˓→+b=2000000"
11.15 How do I do False Eastings and False Northings?
Use +x_0 and +y_0 in the projection string.
204 Chapter 11. FAQ

CHAPTER
TWELVE
GLOSSARY
Pseudocylindrical Projection Pseudocylindrical projections have the mathematical characteristics of
𝑥 = 𝑓 (𝜆, 𝜑)
𝑦 = 𝑔(𝜑)
where the parallels of latitude are straight lines, like cylindrical projections, but the meridians are curved toward
the center as they depart from the equator. This is an effort to minimize the distortion of the polar regions
inherent in the cylindrical projections.
Pseudocylindrical projections are almost exclusively used for small scale global displays and, except for the
Sinusoidal projection, only derived for a spherical Earth. Because of the basic definition none of the pseudo-
cylindrical projections are conformal but many are equal area.
To further reduce distortion, pseudocylindrical are often presented in interrupted form that are made by join-
ing several regions with appropriate central meridians and false easting and clipping boundaries. Interrupted
Homolosine constructions are suited for showing respective global land and oceanic regions, for example. To
reduce the lateral size of the map, some uses remove an irregular, North-South strip of the mid-Atlantic region
so that the western tip of Africa is plotted north of the eastern tip of South America.
205
206 Chapter 12. Glossary

BIBLIOGRAPHY
[AltamimiEtAl2002] Altamimi, Z., P. Sillard, and C. Boucher (2002), ITRF2000: A new release of the In-
ternational Terrestrial Reference Frame for earth science applications, J. Geophys. Res., 107(B10), 2214,
doi:10.1029/2001JB000561.
[Bessel1825] F. W. Bessel, 1825, The calculation of longitude and latitude from geodesic measurements, Astron.
Nachr. 331(8), 852–861 (2010), translated by C. F. F. Karney and R. E. Deakin.
[CalabrettaGreisen2002] M. Calabretta and E. Greisen, 2002, “Representations of celestial coordinates in FITS”.
Astronomy & Astrophysics 395, 3, 1077–1122.
[ChanONeil1975] F. Chan and E. M. O’Neill, 1975, “Feasibility Study of a Quadrilateralized Spherical Cube Earth
Data Base”, Tech. Rep. EPRF 2-75 (CSC), Environmental Prediction Research Facility.
[Danielsen1989] J. Danielsen, 1989, The area under the geodesic, Survey Review 30(232), 61–66.
[Deakin2004] R.E. Deakin, 2004, The Standard and Abridged Molodensky Coordinate Transformation Formulae.
[EberHewitt1979] L. E. Eber and R.P. Hewitt, 1979, Conversion algorithms for the CalCOFI station grid, California
Cooperative Oceanic Fisheries Investigations Reports 20:135-137.
[Evenden1995] G. I. Evenden, 1995, Cartograpic Projection Procedures for the UNIX Environment - A User’s Man-
ual.
[Evenden2005] G. I. Evenden, 2005, libproj4: A Comprehensive Library of Cartographic Projection Functions (Pre-
liminary Draft).
[EversKnudsen2017] K. Evers and T. Knudsen, 2017, Transformation pipelines for PROJ.4, FIG Working Week 2017
Proceedings.
[GeodesicBib] A geodesic bibliography.
[GeodesicWiki] The wikipedia page, Geodesics on an ellipsoid.
[Häkli2016] P. Häkli, M. Lidberg, L. Jivall, et al, 2016, The NKG2008 GPS Campaign - final transformation results
and a new common Nordic reference frame, Journal of Geodetic Science, 6(1).
[Helmert1880] F. R. Helmert, 1880, Mathematical and Physical Theories of Higher Geodesy, Vol 1, (Teubner,
Leipzig), Chaps. 5–7.
[Karney2011] C. F. F. Karney, 2011, Geodesics on an ellipsoid of revolution; errata.
[Karney2013] C. F. F. Karney, 2013, Algorithms for geodesics, J. Geodesy 87(1) 43–55; addenda.
[Komsta2016] L. Komsta, 2016, ATPOL geobotanical grid revisited - a proposal of coordinate conversion algorithms,
Annales UMCS Sectio E Agricultura 71(1), 31–37.
[LambersKolb2012] M. Lambers and A. Kolb, 2012, “Ellipsoidal Cube Maps for Accurate Rendering of Planetary-
Scale Terrain Data”, Proc. Pacific Graphics (Short Papers).
207
[ONeilLaubscher1976] E. M. O’Neill and R. E. Laubscher, 1976, “Extended Studies of a Quadrilateralized Spherical

Cube Earth Data Base”, Tech. Rep. NEPRF 3-76 (CSC), Naval Environmental Prediction Research Facility.
[Snyder1987] J. P. Snyder, 1987, Map Projections - A Working Manual. U.S. Geological Survey professional paper
1395.
[Snyder1993] J. P. Snyder, 1993, Flattening the Earth, Chicago and London, The University of Chicago press.
[Steers1970] J. A. Steers, 1970, An introduction to the study of map projections (15th ed.), London Univ. Press, p.
229.
[Verey2017] M. Verey, 2017, Theoretical analysis and practical consequences of adopting an ATPOL grid model as a
conical projection, defining the conversion of plane coordinates to the WGS-84 ellipsoid, Fragmenta Floristica et
Geobotanica Polonica (preprint submitted).
[Vincenty1975] T. Vincenty, 1975, Direct and inverse solutions of geodesics on the ellipsoid with application of nested
equations, Survey Review 23(176), 88–93.
[WeberMoore2013] E. D. Weber and T.J. Moore, 2013, Corrected Conversion Algorithms For The CalCOFI Sta-
tion Grid And Their Implementation In Several Computer Languages, California Cooperative Oceanic Fisheries
Investigations Reports 54.
[Zajac1978] A. Zajac, 1978, “Atlas of distribution of vascular plants in Poland (ATPOL)”, Taxon 27(5/6), 481–484.
208 Bibliography
INDEX
Symbols command line option, 35, 87, 118

+R=<value> +lat_0=<value>
command line option, 34, 36–40, 44, 46, 49, 58, 63, command line option, 35, 37, 40, 46, 57, 101, 110,
66, 70, 73, 87, 90, 94, 97, 101, 118, 122, 131 117, 122
+abridged +lat_1=<value>
command line option, 144 command line option, 34, 49
+azi=<value> +lat_2=<value>
command line option, 121 command line option, 34
+da=<value> +lat_b
+datum=<value> +lat_ts=<value>
command line option, 135 command line option, 35, 57, 87
+df=<value> +lon_0=<value>
command line option, 144 command line option, 34, 35, 37, 38, 40, 46, 49, 57,
+drx=<value> 63, 66, 70, 72, 75, 87, 90, 94, 97, 101, 110, 117,
command line option, 141 122
+dry=<value> +no_cut
+drz=<value> +north_square
+ds=<value> +order=<list>
+dx=<value> +rx=<value>
command line option, 140, 144 command line option, 140
+dy=<value> +ry=<value>
+dz=<value> +rz=<value>
+ellps=<value> +s=<value>
command line option, 34, 36, 39, 44, 46, 58, 63, 66, command line option, 140
73, 75, 87, 110, 117, 134, 135, 144 +south_square
+exact command line option, 74
command line option, 141 +step
+grids=<list> command line option, 149
command line option, 146, 147 +sweep=<axis>
+guam command line option, 66
command line option, 35 +t_epoch=<time>
+h=<value> command line option, 146, 148
command line option, 65, 97, 121 +t_epoch=<value>
+inv command line option, 138, 141
command line option, 149 +t_final=<time>
+k_0=<value> command line option, 146, 148
209
+t_in=<unit> proj command line option, 20

command line option, 136 -T <ulow,uhi,vlow,vhi,res[,umax,vmax]>
+t_obs=<value> proj command line option, 21
command line option, 138, 141 -V
+t_out=<unit> proj command line option, 20
command line option, 136 -W<n>
+theta=<value> cs2cs command line option, 24
command line option, 140 geod command line option, 26
+tilt=<value> proj command line option, 20
command line option, 121 -a
+towgs84=<list> geod command line option, 25
command line option, 135 -b
+transpose proj command line option, 19
command line option, 141 -c <x,y,z,t>
+x=<value> cct command line option, 22
command line option, 140 -e <string>
+x_0=<value> cs2cs command line option, 23
command line option, 34, 36–40, 46, 49, 57, 63, 66, proj command line option, 19
70, 72, 75, 87, 90, 94, 97, 101, 110, 118, 122, -f <format>
131 cs2cs command line option, 24
+xy_grids=<list> geod command line option, 26
command line option, 138 proj command line option, 20
+xy_in=<unit> -h, –help
+xy_out=<unit> -i
+y=<value> -l, –list
+y_0=<value> -lP
command line option, 34, 36–40, 46, 49, 57, 63, 66, cs2cs command line option, 24
70, 72, 75, 87, 90, 94, 97, 101, 110, 118, 122, proj command line option, 20
131 -l<[=id]>
+z=<value> cs2cs command line option, 24
+z_grids=<list> -ld
command line option, 138 cs2cs command line option, 24
+z_in=<unit> proj command line option, 20
command line option, 136 -le
+z_out=<unit> cs2cs command line option, 24
command line option, 136 geod command line option, 26
–version proj command line option, 20
cct command line option, 22 -lp
command line option, 28 cs2cs command line option, 24
-E proj command line option, 20
cs2cs command line option, 24 -lu
proj command line option, 20 cs2cs command line option, 24
-F <format> geod command line option, 26
geod command line option, 26 proj command line option, 20
-I -m <mult>
cct command line option, 22 proj command line option, 20
cs2cs command line option, 23 -o
geod command line option, 25 proj command line option, 19
proj command line option, 19 -o <file>, –output <file>
-S command line option, 27
210 Index
-o <output file name>, –output=<output file name> +da=<value>, 144

cct command line option, 22 +datum=<value>, 135
-p +df=<value>, 144
geod command line option, 26 +drx=<value>, 141
-q, –quiet +dry=<value>, 141
command line option, 28 +drz=<value>, 141
-r +ds=<value>, 141
cs2cs command line option, 24 +dx=<value>, 140, 144
proj command line option, 20 +dy=<value>, 140, 144
-s +dz=<value>, 140, 144
cs2cs command line option, 24 +ellps=<value>, 34, 36, 39, 44, 46, 58, 63, 66, 73,
proj command line option, 20 75, 87, 110, 117, 134, 135, 144
-s <n>, –skip-lines=<n> +exact, 141
cct command line option, 22 +grids=<list>, 146, 147
-t <time>, –time=<time> +guam, 35
cct command line option, 22 +h=<value>, 65, 97, 121
-t<a> +inv, 149
cs2cs command line option, 23 +k_0=<value>, 35, 87, 118
geod command line option, 25 +lat_0=<value>, 35, 37, 40, 46, 57, 101, 110, 117,
proj command line option, 19 122
-v +lat_1=<value>, 34, 49
cs2cs command line option, 24 +lat_2=<value>, 34
proj command line option, 20 +lat_b, 37
-v, –verbose +lat_ts=<value>, 35, 57, 87
cct command line option, 22 +lon_0=<value>, 34, 35, 37, 38, 40, 46, 49, 57, 63,
command line option, 28 66, 70, 72, 75, 87, 90, 94, 97, 101, 110, 117,
-w<n> 122
cs2cs command line option, 24 +no_cut, 37
geod command line option, 26 +north_square, 74
proj command line option, 20 +order=<list>, 134
-z <height>, –height=<height> +rx=<value>, 140
cct command line option, 22 +ry=<value>, 140
+rz=<value>, 140
A +s=<value>, 140
accept <x y [z [t]]> +south_square, 74
command line option, 29 +step, 149
+sweep=<axis>, 66
C +t_epoch=<time>, 146, 148
cct, 21 +t_epoch=<value>, 138, 141
cct command line option +t_final=<time>, 146, 148
–version, 22 +t_in=<unit>, 136
-I, 22 +t_obs=<value>, 138, 141
-c <x,y,z,t>, 22 +t_out=<unit>, 136
-o <output file name>, –output=<output file name>, +theta=<value>, 140
22 +tilt=<value>, 121
-s <n>, –skip-lines=<n>, 22 +towgs84=<list>, 135
-t <time>, –time=<time>, 22 +transpose, 141
-v, –verbose, 22 +x=<value>, 140
-z <height>, –height=<height>, 22 +x_0=<value>, 34, 36–40, 46, 49, 57, 63, 66, 70, 72,
command line option 75, 87, 90, 94, 97, 101, 110, 118, 122, 131
+R=<value>, 34, 36–40, 44, 46, 49, 58, 63, 66, 70, +xy_grids=<list>, 138
73, 87, 90, 94, 97, 101, 118, 122, 131 +xy_in=<unit>, 136
+abridged, 144 +xy_out=<unit>, 136
+azi=<value>, 121 +y=<value>, 140
Index 211
+y_0=<value>, 34, 36–40, 46, 49, 57, 63, 66, 70, 72, -F <format>, 26
75, 87, 90, 94, 97, 101, 110, 118, 122, 131 -I, 25
+z=<value>, 140 -W<n>, 26
+z_grids=<list>, 138 -a, 25
+z_in=<unit>, 136 -f <format>, 26
+z_out=<unit>, 136 -le, 26
–version, 28 -lu, 26
-h, –help, 27 -p, 26
-l, –list, 28 -t<a>, 25
-o <file>, –output <file>, 27 -w<n>, 26
-q, –quiet, 28 gie, 27
-v, –verbose, 28
accept <x y [z [t]]>, 29 I
direction <direction>, 30 ignore <error code>
echo <text>, 31 command line option, 30
expect <x y [z [t]]> | <error code>, 29
ignore <error code>, 30 O
operation <+args>, 29 operation <+args>
roundtrip <n> <tolerance>, 30 command line option, 29
skip, 31
tolerance <tolerance>, 29 P
cs2cs command line option PJ (C type), 166
-E, 24 PJ_AREA (C type), 166
-I, 23 PJ_CONTEXT (C type), 166
-W<n>, 24 PJ_COORD (C type), 169
-e <string>, 23 PJ_COORD.PJ_COORD.lp (C member), 170
-f <format>, 24 PJ_COORD.PJ_COORD.lpz (C member), 170
-lP, 24 PJ_COORD.PJ_COORD.lpzt (C member), 170
-l<[=id]>, 24 PJ_COORD.PJ_COORD.uv (C member), 170
-ld, 24 PJ_COORD.PJ_COORD.uvw (C member), 170
-le, 24 PJ_COORD.PJ_COORD.uvwt (C member), 170
-lp, 24 PJ_COORD.PJ_COORD.xy (C member), 170
-lu, 24 PJ_COORD.PJ_COORD.xyz (C member), 170
-r, 24 PJ_COORD.PJ_COORD.xyzt (C member), 170
-s, 24 PJ_DIRECTION (C type), 166
-t<a>, 23 PJ_DIRECTION.PJ_FWD (C member), 166
-v, 24 PJ_DIRECTION.PJ_IDENT (C member), 166
-w<n>, 24 PJ_DIRECTION.PJ_INV (C member), 166
PJ_ELLPS (C type), 172
D PJ_ELLPS.ell (C member), 172
direction <direction> PJ_ELLPS.id (C member), 172
command line option, 30 PJ_ELLPS.major (C member), 172
PJ_ELLPS.name (C member), 172
E PJ_FACTORS (C type), 170
echo <text> PJ_FACTORS.PJ_FACTORS.angular_distortion (C
command line option, 31 member), 171
environment variable PJ_FACTORS.PJ_FACTORS.areal_scale (C member),
PROJ_DEBUG, 17 171
PROJ_LIB, 7, 8, 17, 21, 24, 176 PJ_FACTORS.PJ_FACTORS.dx_dlam (C member), 171
expect <x y [z [t]]> | <error code> PJ_FACTORS.PJ_FACTORS.dx_dphi (C member), 171
command line option, 29 PJ_FACTORS.PJ_FACTORS.dy_dlam (C member), 171
PJ_FACTORS.PJ_FACTORS.dy_dphi (C member), 171
G PJ_FACTORS.PJ_FACTORS.meridian_convergence (C
geod command line option member), 171
212 Index
PJ_FACTORS.PJ_FACTORS.meridian_parallel_angle PJ_OPERATIONS.op (C member), 171

(C member), 171 PJ_OPK (C type), 169
PJ_FACTORS.PJ_FACTORS.meridional_scale (C mem- PJ_OPK.PJ_OPK.k (C member), 169
ber), 171 PJ_OPK.PJ_OPK.o (C member), 169
PJ_FACTORS.PJ_FACTORS.parallel_scale (C member), PJ_OPK.PJ_OPK.p (C member), 169
171 PJ_PRIME_MERIDIANS (C type), 172
PJ_FACTORS.PJ_FACTORS.tissot_semimajor (C mem- PJ_PRIME_MERIDIANS.def (C member), 172
ber), 171 PJ_PRIME_MERIDIANS.id (C member), 172
PJ_FACTORS.PJ_FACTORS.tissot_semiminor (C mem- PJ_PROJ_INFO (C type), 173
ber), 171 PJ_PROJ_INFO.PJ_PROJ_INFO.accuracy (C member),
PJ_GRID_INFO (C type), 174 174
PJ_GRID_INFO.PJ_GRID_INFO (C member), 174 PJ_PROJ_INFO.PJ_PROJ_INFO.definition (C member),
PJ_GRID_INFO.PJ_GRID_INFO.cs_lat (C member), 173
174 PJ_PROJ_INFO.PJ_PROJ_INFO.description (C mem-
PJ_GRID_INFO.PJ_GRID_INFO.cs_lon (C member), ber), 173
174 PJ_PROJ_INFO.PJ_PROJ_INFO.has_inverse (C mem-
PJ_GRID_INFO.PJ_GRID_INFO.lowerleft (C member), ber), 174
174 PJ_PROJ_INFO.PJ_PROJ_INFO.id (C member), 173
PJ_GRID_INFO.PJ_GRID_INFO.n_lat (C member), 174 PJ_UNITS (C type), 172
PJ_GRID_INFO.PJ_GRID_INFO.n_lon (C member), PJ_UNITS.factor (C member), 172
174 PJ_UNITS.id (C member), 172
PJ_GRID_INFO.PJ_GRID_INFO.upperright (C mem- PJ_UNITS.name (C member), 172
ber), 174 PJ_UNITS.to_meter (C member), 172
PJ_INFO (C type), 173 PJ_UV (C type), 167
PJ_INFO.PJ_INFO.major (C member), 173 PJ_UV.PJ_UV.u (C member), 167
PJ_INFO.PJ_INFO.minor (C member), 173 PJ_UV.PJ_UV.v (C member), 167
PJ_INFO.PJ_INFO.patch (C member), 173 PJ_UVW (C type), 168
PJ_INFO.PJ_INFO.release (C member), 173 PJ_UVW.PJ_UVW.u (C member), 168
PJ_INFO.PJ_INFO.searchpath (C member), 173 PJ_UVW.PJ_UVW.v (C member), 168
PJ_INFO.PJ_INFO.version (C member), 173 PJ_UVW.PJ_UVW.w (C member), 168
PJ_INIT_INFO (C type), 174 PJ_UVWT (C type), 169
PJ_INIT_INFO.PJ_INIT_INFO.lastupdate (C member), PJ_UVWT.PJ_UVWT.e (C member), 169
175 PJ_UVWT.PJ_UVWT.n (C member), 169
PJ_LOG_FUNC (C type), 175 PJ_UVWT.PJ_UVWT.t (C member), 169
PJ_LOG_LEVEL (C type), 175 PJ_UVWT.PJ_UVWT.w (C member), 169
PJ_LOG_LEVEL.PJ_LOG_DEBUG (C member), 175 PJ_XY (C type), 167
PJ_LOG_LEVEL.PJ_LOG_ERROR (C member), 175 PJ_XY.PJ_XY.x (C member), 167
PJ_LOG_LEVEL.PJ_LOG_NONE (C member), 175 PJ_XY.PJ_XY.y (C member), 167
PJ_LOG_LEVEL.PJ_LOG_TELL (C member), 175 PJ_XYZ (C type), 168
PJ_LOG_LEVEL.PJ_LOG_TRACE (C member), 175 PJ_XYZ.PJ_XYZ.x (C member), 168
PJ_LP (C type), 167 PJ_XYZ.PJ_XYZ.y (C member), 168
PJ_LP.PJ_LP.lam (C member), 167 PJ_XYZ.PJ_XYZ.z (C member), 168
PJ_LP.PJ_LP.phi (C member), 167 PJ_XYZT (C type), 168
PJ_LPZ (C type), 167 PJ_XYZT.PJ_XYZT.t (C member), 169
PJ_LPZ.PJ_LPZ.lam (C member), 167 PJ_XYZT.PJ_XYZT.x (C member), 169
PJ_LPZ.PJ_LPZ.phi (C member), 167 PJ_XYZT.PJ_XYZT.y (C member), 169
PJ_LPZ.PJ_LPZ.z (C member), 167 PJ_XYZT.PJ_XYZT.z (C member), 169
PJ_LPZT (C type), 168 proj, 19
PJ_LPZT.PJ_LPZT.lam (C member), 168 proj command line option
PJ_LPZT.PJ_LPZT.phi (C member), 168 -E, 20
PJ_LPZT.PJ_LPZT.t (C member), 168 -I, 19
PJ_LPZT.PJ_LPZT.z (C member), 168 -S, 20
PJ_OPERATIONS (C type), 171 -T <ulow,uhi,vlow,vhi,res[,umax,vmax]>, 21
PJ_OPERATIONS.id (C member), 171 -V, 20
Index 213
-W<n>, 20 proj_trans_generic (C function), 177

-b, 19 proj_xy_dist (C function), 182
-e <string>, 19 proj_xyz_dist (C function), 182
-f <format>, 20 Pseudocylindrical Projection, 205
-i, 19
-lP, 20 R
-l<[=id]>, 20 roundtrip <n> <tolerance>
-ld, 20 command line option, 30
-le, 20
-lp, 20 S
-lu, 20 skip
-m <mult>, 20 command line option, 31
-o, 19
-r, 20 T
-s, 20
-t<a>, 19 tolerance <tolerance>
-v, 20 command line option, 29
-w<n>, 20
proj_angular_input (C function), 184
proj_angular_output (C function), 184
proj_context_create (C function), 175
proj_context_destroy (C function), 176
proj_coord (C function), 182
proj_create (C function), 176
proj_create_argv (C function), 176
proj_create_crs_to_crs (C function), 176
proj_destroy (C function), 177
proj_dmstor (C function), 183
proj_errno (C function), 179
proj_errno_reset (C function), 179
proj_errno_restore (C function), 179
proj_errno_set (C function), 179
proj_errno_string (C function), 180
proj_factors (C function), 183
proj_geocentric_latitude (C function), 184
proj_grid_info (C function), 180
proj_info (C function), 180
proj_init_info (C function), 181
PROJ_LIB, 7, 8, 17, 21, 24, 176
proj_list_ellps (C function), 181
proj_list_operations (C function), 181
proj_list_prime_meridians (C function), 181
proj_list_units (C function), 181
proj_log_func (C function), 180
proj_log_level (C function), 180
proj_lp_dist (C function), 181
proj_lpz_dist (C function), 182
proj_pj_info (C function), 180
proj_roundtrip (C function), 183
proj_rtodms (C function), 184
proj_todeg (C function), 183
proj_torad (C function), 183
proj_trans (C function), 177
proj_trans_array (C function), 179
214 Index

Proj PDF

Uploaded by

Document Informationclick to expand document information

Document Informationclick to expand document information

Copyright:

Available Formats

Proj PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Proj PDF

Uploaded by

Copyright:

Available Formats

PROJ coordinate transformation

Jun 01, 2018

7 Resource files 151

8 Geodesic calculations 159

To cite PROJ in publications use:

2.1 Current Release

• 2018-06-01 proj-5.1.0.tar.gz (md5)

2.2 Past Releases

• 2018-04-01 proj-5.0.1.tar.gz (md5)

3.1 Installation from package management systems

3.1.1 Cross platform

PROJ is also available via cross platform package managers.

conda install -c conda-forge proj4

docker pull osgeo/proj.4

1. Download either the 32 bit or 64 bit installer.

3. Select “Advanced Install” and press Next.

sudo apt-get install proj-bin

On Red Hat based system packages are installed with yum:

sudo yum install proj

On OS X PROJ can be installed via the Homebrew package manager:

brew install proj

PROJ is also available from the MacPorts system:

sudo ports install proj

3.2 Compilation and installation from source code

FSF’s configuration procedure is used to ease installation of the PROJ system.

If another path prefix is required, then execute:

unzip proj-datumgrid-1.7.zip -d proj-5.0.1/nad/

The install target will create, if necessary, all required sub-directories.

3.2. Compilation and installation from source code 7

Create a build directory and step into it:

On Windows, one may need to specify generator:

cmake -G "Visual Studio 15 2017" ..

Tests are run with:

4.1 Quick start

+proj=merc +lat_ts=56.5 +ellps=GRS80

$ proj +proj=merc +lat_ts=56.5 +ellps=GRS80

$ echo 55.2 12.2 | proj +proj=merc +lat_ts=56.5 +ellps=GRS80

$ echo 3399483.80 752085.60 | cs2cs +proj=merc +lat_ts=56.5 +ellps=GRS80 +to

6103992.36 1924052.47 0.00

$ echo 56 12 | cs2cs +init=epsg:4326 +to +init=epsg:25832

4.2 Cartographic projection

In the sections below most of the parameters are explained in details.

10 Chapter 4. Using PROJ

4.2.2 False Easting/Northing

4.2.3 Longitude Wrapping

4.2.4 Prime Meridian

4.2. Cartographic projection 11

cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid

4.2.5 Axis orientation

4.3 Geodetic transformation

12 Chapter 4. Using PROJ

4. Convert back from cartesian to geographic coordinates

4.3.1 Transformation pipelines

4.3. Geodetic transformation 13

(continued from previous page)

4.3.2 cs2cs paradigm

14 Chapter 4. Using PROJ