1GIE(1)                               PROJ                               GIE(1)
2
3
4

NAME

6       gie - The Geospatial Integrity Investigation Environment
7

SYNOPSIS

9          gie [ -hovql [ args ] ] file[s]
10

DESCRIPTION

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
18       -h, --help
19              Print usage information
20
21       -o <file>, --output <file>
22              Specify output file name
23
24       -v, --verbose
25              Verbose:  Provide  non-essential informational output. Repeat -v
26              for more verbosity (e.g. -vv)
27
28       -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
33       -l, --list
34              List the PROJ internal system error codes
35
36       --version
37              Print version number
38
39       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
46       A  sample  test  file  for gie that uses the three above basic commands
47       looks like:
48
49          <gie>
50
51          --------------------------------------------
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
59          </gie>
60
61       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
66       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
71       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
79       Below the gie command language is explained in details.
80

EXAMPLES

82       1. Run all tests in a file with all debug information turned on
83
84          gie -vvvv corner-cases.gie
85
86       2. Run all tests in several files
87
88          gie foo bar
89

GIE COMMAND LANGUAGE

91       operation <+args>
92              Define a PROJ operation to test. Example:
93
94                 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
99                 # test 2D function
100                 accept    12 56
101                 expect    687071.4391   6210141.3267
102
103       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
113              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
119              See operation for an example.
120
121       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
128              See operation for an example.
129
130              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
137                 operation   proj=pipeline step
138                             proj=urm5 n=0.5 inv
139                 expect      failure pjd_err_malformed_pipeline
140
141              See gie --list for a list of error codes that can be expected.
142
143       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
151                 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
157                 # 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
164              The default tolerance is 0.5 mm. See proj -lu for a list of pos‐
165              sible units.
166
167       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
176              Example with the default 100 iterations and the  default  toler‐
177              ance:
178
179                 operation       proj=merc
180                 accept          12 55
181                 roundtrip
182
183              Example with count and default tolerance:
184
185                 operation       proj=merc
186                 accept          12 55
187                 roundtrip       10000
188
189              Example with count and tolerance:
190
191                 operation       proj=merc
192                 accept          12 55
193                 roundtrip       10000 5 mm
194
195       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
202                 operation proj=pipeline zone=32 step
203                           proj=utm  ellps=GRS80 step
204                           proj=utm  ellps=GRS80 inv
205                 tolerance 0.1 mm
206
207                 accept 12 55 0 0
208                 expect 12 55 0 0
209
210                 # Now the inverse direction (still same result: the pipeline is symmetrical)
211
212                 direction inverse
213                 expect 12 55 0 0
214
215              The default direction is "forward".
216
217       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
222                 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
228              See gie --list for a list of error codes that can be ignored.
229
230       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
236       echo <text>
237              Add user defined text to the output stream. See the example  be‐
238              low.
239
240                 <gie>
241                 echo ** Mercator projection tests **
242                 operation +proj=merc
243                 accept  0   0
244                 expect  0   0
245                 </gie>
246
247              which returns
248
249                 -------------------------------------------------------------------------------
250                 Reading file 'test.gie'
251                 ** Mercator projection test **
252                 -------------------------------------------------------------------------------
253                 total:  1 tests succeeded,  0 tests skipped,  0 tests failed.
254                 -------------------------------------------------------------------------------
255
256       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
261                 <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

STRICT MODE

271       New in version 7.1.
272
273
274       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
281              <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

BACKGROUND

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
300       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
306       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
310       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
317       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
323       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
326       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

SEE ALSO

331       proj(1), cs2cs(1), cct(1), geod(1), projinfo(1), projsync(1)
332

BUGS

334       A      list      of      know      bugs     can     be     found     at
335       https://github.com/OSGeo/PROJ/issues where new bug reports can be  sub‐
336       mitted to.
337

HOME PAGE

339       https://proj.org/
340

AUTHOR

342       Thomas Knudsen
343
345       1983-2020
346
347
348
349
3507.2.1                            Dec 25, 2020                           GIE(1)
Impressum