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
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
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
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
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
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
128              See operation for an example.
129
130              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
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
173              coordinate  is  within  the set tolerance of the initial coordi‐
174              nate, 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
238              below.
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

BACKGROUND

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
277       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
283       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
287       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
294       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
300       It  is  only  reasonable  to  name  a  program,  keeping  an eye on the
301       integrity of the PROJ system, in honour of Gerald.
302
303       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

SEE ALSO

308       proj(1), cs2cs(1), cct(1), geod(1)
309

BUGS

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

HOME PAGE

316       https://proj.org/
317

AUTHOR

319       Thomas Knudsen
320
322       1983-2020
323
324
325
326
3276.3.2                            Apr 27, 2020                           GIE(1)
Impressum