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 ex‐
40 tension .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 op‐
109 eration is tested (2D, 3D or 4D). Many coordinates can be ac‐
110 cepted for one operation. For each accept an accompanying expect
111 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 ac‐
123 cepted coordinate passed though an operation. The expected coor‐
124 dinate can be defined by either 2, 3 or 4 components, similarly
125 to accept. Many coordinates can be expected for one operation.
126 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 ex‐
131 pect 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 co‐
173 ordinate is within the set tolerance of the initial coordinate,
174 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 be‐
238 low.
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 New in version 7.1.
272 A stricter variant of normal gie syntax can be used by wrapping gie
275 commands between <gie-strict> and </gie-strict>. In strict mode, com‐
276 ment lines must start with a sharp character. Unknown commands will be
277 considered as an error. A command can still be split on several lines,
278 but intermediate lines must end with the space character followed by
279 backslash to mark the continuation.
280 <gie-strict>
282 # This is a comment. The following line with multiple repeated characters too
283 -------------------------------------------------
284 # A command on several lines must use " \" continuation
285 operation proj=hgridshift +grids=nzgd2kgrid0005.gsb \
286 ellps=GRS80
287 tolerance 1 mm
288 ignore pjd_err_failed_to_load_grid
289 accept 172.999892181021551 -45.001620431954613
290 expect 173 -45
291 </gie-strict>
292
294 More importantly than being an acronym for "Geospatial Integrity Inves‐
295 tigation Environment", gie were also the initials, user id, and USGS
296 email address of Gerald Ian Evenden (1935--2016), the geospatial vi‐
297 sionary, who, already in the 1980s, started what was to become the PROJ
298 of today.
299 Gerald's clear vision was that map projections are just special func‐
301 tions. Some of them rather complex, most of them of two variables, but
302 all of them just special functions, and not particularly more special
303 than the sin(), cos(), tan(), and hypot() already available in the C
304 standard library.
305 And hence, according to Gerald, they should not be particularly much
307 harder to use, for a programmer, than the sin()'s, tan()'s and hy‐
308 pot()'s so readily available.
309 Gerald's ingenuity also showed in the implementation of the vision,
311 where he devised a comprehensive, yet simple, system of key-value pairs
312 for parameterising a map projection, and the highly flexible PJ struct,
313 storing run-time compiled versions of those key-value pairs, hence mak‐
314 ing a map projection function call, pj_fwd(PJ, point), as easy as a
315 traditional function call like hypot(x,y).
316 While today, we may have more formally well defined metadata systems
318 (most prominent the OGC WKT2 representation), nothing comes close being
319 as easily readable ("human compatible") as Gerald's key-value system.
320 This system in particular, and the PROJ system in general, was Gerald's
321 great gift to anyone using and/or communicating about geodata.
322 It is only reasonable to name a program, keeping an eye on the integ‐
324 rity of the PROJ system, in honour of Gerald.
325 So in honour, and hopefully also in the spirit, of Gerald Ian Evenden
327 (1935--2016), this is the Geospatial Integrity Investigation Environ‐
328 ment.
329
331 proj(1), cs2cs(1), cct(1), geod(1), projinfo(1), projsync(1)
332
334 A list of known bugs can be found at
335 https://github.com/OSGeo/PROJ/issues where new bug reports can be sub‐
336 mitted to.
337
339 https://proj.org/
340
342 Thomas Knudsen
343
345 1983-2023
3469.2.1 Jun 1, 2023 GIE(1)