1GIE(1) PROJ GIE(1)
2
6 gie - The Geospatial Integrity Investigation Environment
7
9 gie [ -hovql [ args ] ] file[s]
10
12 gie, the Geospatial Integrity Investigation Environment, is a regres‐
13 sion testing environment for the PROJ transformation library. Its pri‐
14 mary design goal is to be able to perform regression testing of code
15 that are a part of PROJ, while not requiring any other kind of tooling
16 than the same C compiler already employed for compiling the library.
17 -h, --help
19 Print usage information
20 -o <file>, --output <file>
22 Specify output file name
23 -v, --verbose
25 Verbose: Provide non-essential informational output. Repeat -v
26 for more verbosity (e.g. -vv)
27 -q, --quiet
29 Quiet: Opposite of verbose. In quiet mode not even errors are
30 reported. Only interaction is through the return code (0 on suc‐
31 cess, non-zero indicates number of FAILED tests)
32 -l, --list
34 List the PROJ internal system error codes
35 --version
37 Print version number
38 Tests for gie are defined in simple text files. Usually having the
40 extension .gie. Test for gie are written in the purpose-build command
41 language for gie. The basic functionality of the gie command language
42 is implemented through just 3 command verbs: operation, which defines
43 the PROJ operation to test, accept, which defines the input coordinate
44 to read, and expect, which defines the result to expect.
45 A sample test file for gie that uses the three above basic commands
47 looks like:
48 <gie>
50 --------------------------------------------
52 Test output of the UTM projection
53 --------------------------------------------
54 operation +proj=utm +zone=32 +ellps=GRS80
55 --------------------------------------------
56 accept 12 55
57 expect 691_875.632_14 6_098_907.825_05
58 </gie>
60 Parsing of a gie file starts at <gie> and ends when </gie> is reached.
62 Anything before <gie> and after </gie> is not considered. Test cases
63 are created by defining an operation which accept an input coordinate
64 and expect an output coordinate.
65 Because gie tests are wrapped in the <gie>/</gie> tags it is also pos‐
67 sible to add test cases to custom made init files. The tests will be
68 ignore by PROJ when reading the init file with +init and gie ignores
69 anything not wrapped in <gie>/</gie>.
70 gie tests are defined by a set of commands like operation, accept and
72 expect in the example above. Together the commands make out the gie
73 command language. Any line in a gie file that does not start with a
74 command is ignored. In the example above it is seen how this can be
75 used to add comments and styling to gie test files in order to make
76 them more readable as well as documenting what the purpose of the vari‐
77 ous tests are.
78 Below the gie command language is explained in details.
80
82 1. Run all tests in a file with all debug information turned on
83 gie -vvvv corner-cases.gie
85 2. Run all tests in several files
87 gie foo bar
89
91 operation <+args>
92 Define a PROJ operation to test. Example:
93 operation proj=utm zone=32 ellps=GRS80
95 # test 4D function
96 accept 12 55 0 0
97 expect 691875.63214 6098907.82501 0 0
98 # test 2D function
100 accept 12 56
101 expect 687071.4391 6210141.3267
102 accept <x y [z [t]]>
104 Define the input coordinate to read. Takes test coordinate. The
105 coordinate can be defined by either 2, 3 or 4 values, where the
106 first two values are the x- and y-components, the 3rd is the
107 z-component and the 4th is the time component. The number of
108 components in the coordinate determines which version of the
109 operation is tested (2D, 3D or 4D). Many coordinates can be
110 accepted for one operation. For each accept an accompanying
111 expect is needed.
112 Note that gie accepts the underscore (_) as a thousands separa‐
114 tor. It is not required (in fact, it is entirely ignored by the
115 input routine), but it significantly improves the readability of
116 the very long strings of numbers typically required in projected
117 coordinates.
118 See operation for an example.
120 expect <x y [z [t]]> | <error code>
122 Define the expected coordinate that will be returned from
123 accepted coordinate passed though an operation. The expected
124 coordinate can be defined by either 2, 3 or 4 components, simi‐
125 larly to accept. Many coordinates can be expected for one
126 operation. For each expect an accompanying accept is needed.
127 See operation for an example.
129 In addition to expecting a coordinate it is also possible to
131 expect a PROJ error code in case an operation can't be created.
132 This is useful when testing that errors are caught and handled
133 correctly. Below is an example of that tests that the pipeline
134 operator fails correctly when a non-invertible pipeline is con‐
135 structed.
136 operation proj=pipeline step
138 proj=urm5 n=0.5 inv
139 expect failure pjd_err_malformed_pipeline
140 See gie --list for a list of error codes that can be expected.
142 tolerance <tolerance>
144 The tolerance command controls how much accepted coordinates can
145 deviate from the expected coordinate. This is handy to test that
146 an operation meets a certain numerical tolerance threshold. Some
147 operations are expected to be accurate within millimeters where
148 others might only be accurate within a few meters. tolerance
149 should
150 operation proj=merc
152 # test coordinate as returned by ```echo 12 55 | proj +proj=merc``
153 tolerance 1 cm
154 accept 12 55
155 expect 1335833.89 7326837.72
156 # test that the same coordinate with a 50 m false easting as determined
158 # by ``echo 12 55 |proj +proj=merc +x_0=50`` is still within a 100 m
159 # tolerance of the unaltered coordinate from proj=merc
160 tolerance 100 m
161 accept 12 55
162 expect 1335883.89 7326837.72
163 The default tolerance is 0.5 mm. See proj -lu for a list of pos‐
165 sible units.
166 roundtrip <n> <tolerance>
168 Do a roundtrip test of an operation. roundtrip needs a operation
169 and a accept command to function. The accepted coordinate is
170 passed to the operation first in it's forward mode, then the
171 output from the forward operation is passed back to the inverse
172 operation. This procedure is done n times. If the resulting
173 coordinate is within the set tolerance of the initial coordi‐
174 nate, the test is passed.
175 Example with the default 100 iterations and the default toler‐
177 ance:
178 operation proj=merc
180 accept 12 55
181 roundtrip
182 Example with count and default tolerance:
184 operation proj=merc
186 accept 12 55
187 roundtrip 10000
188 Example with count and tolerance:
190 operation proj=merc
192 accept 12 55
193 roundtrip 10000 5 mm
194 direction <direction>
196 The direction command specifies in which direction an operation
197 is performed. This can either be forward or inverse. An example
198 of this is seen below where it is tested that a symmetrical
199 transformation pipeline returns the same results in both direc‐
200 tions.
201 operation proj=pipeline zone=32 step
203 proj=utm ellps=GRS80 step
204 proj=utm ellps=GRS80 inv
205 tolerance 0.1 mm
206 accept 12 55 0 0
208 expect 12 55 0 0
209 # Now the inverse direction (still same result: the pipeline is symmetrical)
211 direction inverse
213 expect 12 55 0 0
214 The default direction is "forward".
216 ignore <error code>
218 This is especially useful in test cases that rely on a grid that
219 is not guaranteed to be available. Below is an example of that
220 situation.
221 operation proj=hgridshift +grids=nzgd2kgrid0005.gsb ellps=GRS80
223 tolerance 1 mm
224 ignore pjd_err_failed_to_load_grid
225 accept 172.999892181021551 -45.001620431954613
226 expect 173 -45
227 See gie --list for a list of error codes that can be ignored.
229 require_grid <grid_name>
231 Checks the availability of the grid <grid_name>. If it is not
232 found, then all accept/expect pairs until the next operation
233 will be skipped. require_grid can be repeated several times to
234 specify several grids whose presence is required.
235 echo <text>
237 Add user defined text to the output stream. See the example
238 below.
239 <gie>
241 echo ** Mercator projection tests **
242 operation +proj=merc
243 accept 0 0
244 expect 0 0
245 </gie>
246 which returns
248 -------------------------------------------------------------------------------
250 Reading file 'test.gie'
251 ** Mercator projection test **
252 -------------------------------------------------------------------------------
253 total: 1 tests succeeded, 0 tests skipped, 0 tests failed.
254 -------------------------------------------------------------------------------
255 skip Skip any test after the first occurrence of skip. In the example
257 below only the first test will be performed. The second test is
258 skipped. This feature is mostly relevant for debugging when
259 writing new test cases.
260 <gie>
262 operation proj=merc
263 accept 0 0
264 expect 0 0
265 skip
266 accept 0 1
267 expect 0 110579.9
268 </gie>
269
271 More importantly than being an acronym for "Geospatial Integrity Inves‐
272 tigation Environment", gie were also the initials, user id, and USGS
273 email address of Gerald Ian Evenden (1935--2016), the geospatial
274 visionary, who, already in the 1980s, started what was to become the
275 PROJ of today.
276 Gerald's clear vision was that map projections are just special func‐
278 tions. Some of them rather complex, most of them of two variables, but
279 all of them just special functions, and not particularly more special
280 than the sin(), cos(), tan(), and hypot() already available in the C
281 standard library.
282 And hence, according to Gerald, they should not be particularly much
284 harder to use, for a programmer, than the sin()'s, tan()'s and
285 hypot()'s so readily available.
286 Gerald's ingenuity also showed in the implementation of the vision,
288 where he devised a comprehensive, yet simple, system of key-value pairs
289 for parameterising a map projection, and the highly flexible PJ struct,
290 storing run-time compiled versions of those key-value pairs, hence mak‐
291 ing a map projection function call, pj_fwd(PJ, point), as easy as a
292 traditional function call like hypot(x,y).
293 While today, we may have more formally well defined metadata systems
295 (most prominent the OGC WKT2 representation), nothing comes close being
296 as easily readable ("human compatible") as Gerald's key-value system.
297 This system in particular, and the PROJ system in general, was Gerald's
298 great gift to anyone using and/or communicating about geodata.
299 It is only reasonable to name a program, keeping an eye on the
301 integrity of the PROJ system, in honour of Gerald.
302 So in honour, and hopefully also in the spirit, of Gerald Ian Evenden
304 (1935--2016), this is the Geospatial Integrity Investigation Environ‐
305 ment.
306
308 proj(1), cs2cs(1), cct(1), geod(1)
309
311 A list of know bugs can be found at
312 https://github.com/OSGeo/PROJ/issues where new bug reports can be sub‐
313 mitted to.
314
316 https://proj.org/
317
319 Thomas Knudsen
320
322 1983-2020
3236.3.2 Apr 27, 2020 GIE(1)