diff options
| -rw-r--r-- | man/CMakeLists.txt | 2 | ||||
| -rw-r--r-- | man/man1/Makefile.am | 2 | ||||
| -rw-r--r-- | man/man1/cct.1 | 112 | ||||
| -rw-r--r-- | man/man1/gie.1 | 116 |
4 files changed, 230 insertions, 2 deletions
diff --git a/man/CMakeLists.txt b/man/CMakeLists.txt index bf47b16f..3ca48226 100644 --- a/man/CMakeLists.txt +++ b/man/CMakeLists.txt @@ -1,4 +1,4 @@ -install (FILES man1/proj.1 man1/cs2cs.1 man1/geod.1 +install (FILES man1/proj.1 man1/cs2cs.1 man1/geod.1 man1/cct.1 man1/gie.1 DESTINATION share/man/man1) install (FILES man3/pj_init.3 man3/geodesic.3 diff --git a/man/man1/Makefile.am b/man/man1/Makefile.am index b175aaa0..b8a59ff2 100644 --- a/man/man1/Makefile.am +++ b/man/man1/Makefile.am @@ -1,4 +1,4 @@ -man_MANS = geod.1 proj.1 cs2cs.1 +man_MANS = geod.1 proj.1 cs2cs.1 cct.1 gie.1 EXTRA_DIST = $(man_MANS) diff --git a/man/man1/cct.1 b/man/man1/cct.1 new file mode 100644 index 00000000..b74896f4 --- /dev/null +++ b/man/man1/cct.1 @@ -0,0 +1,112 @@ +.\" release 5 +.\" +.ad b +.hy 1 +.TH CCT 1 "2018/02/25 Rel. 5.0.0" +.SH NAME +cct \- 4D equivalent to the "proj" projection program +.SH SYNOPSIS +.B cct +[\-options]... [+operator_specs]... infile... +.SH DESCRIPTION +.I cct +is a 4D equivalent to the proj(1) projection program. +.PP +cct is an acronym meaning "Coordinate Conversion and Transformation". +.PP +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: +.PP +*Coordinate Conversions*, which are coordinate operations where input +and output datum are identical (e.g. conversion from geographical to +cartesian coordinates) and +.PP +*Coordinate Transformations*, which are coordinate operations where +input and output datums differ (e.g. change of reference frame). +.PP +\fBcct\fR, however, 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 +Amercan Geophysical Union (1991), recipient of the IAG Levallois Medal +(2007), the European Geosciences Union Vening Meinesz Medal (2008), and +of numerous other honours. +.PP +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. +.PP +As Christian was an avid Fortran programmer, and a keen Unix connoiseur, +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. +.PP +Hence, in honour of cct (the geodesist) this is cct (the program). +.SH OPTIONS +.IP "\fB\fB\-o /path/to/file\fR\fR" 1c +Specify output file name\& +.IP "\fB\fB\-c x,y,z,t\fR\fR" 1c +Specify input columns for (up to) 4 input parameters. +Defaults to 1,2,3,4\& +.IP "\fB\fB\-z value\fR\fR" 1c +Provide a fixed z value for all input data (e.g. \-z 0)\& +.IP "\fB\fB\-t value\fR\fR" 1c +Provide a fixed t value for all input data (e.g. \-t 0)\& +.IP "\fB\fB\-I\fR\fR" 1c +Do the inverse transformation\& +.IP "\fB\fB\-v\fR\fR" 1c +Verbose: Provide non-essential informational output. +Repeat \-v for more verbosity (e.g. \-vv)\& +.SH LONG OPTIONS +.IP "\fB\fB\-\-output\fR\fR" 1c +Alias for \-o\& +.IP "\fB\fB\-\-columns\fR\fR" 1c +Alias for \-c\& +.IP "\fB\fB\-\-height\fR\fR" 1c +Alias for \-z\& +.IP "\fB\fB\-\-time\fR\fR" 1c +Alias for \-t\& +.IP "\fB\fB\-\-verbose\fR\fR" 1c +Alias for \-v\& +.IP "\fB\fB\-\-inverse\fR\fR" 1c +Alias for \-I\& +.IP "\fB\fB\-\-help\fR\fR" 1c +Alias for -h\& +.SH OPERATOR SPECS +The operator specs describe the action to be performed by cct, e.g: +.IP ++proj=utm +ellps=GRS80 +zone=32 +.PP +instructs cct to convert input data to Universal Transverse Mercator, zone 32 +coordinates, based on the GRS80 ellipsoid. +.PP +Hence, the command +.IP +echo 12 55 | cct -z0 -t0 +proj=utm +zone=32 +ellps=GRS80 +.PP +Should give results comparable to the classic proj command +.IP +echo 12 55 | proj +proj=utm +zone=32 +ellps=GRS80 +.SH EXAMPLES +1. convert geographical input to UTM zone 32 on the GRS80 ellipsoid: +.IP +cct +proj=utm +ellps=GRS80 +zone=32 +.PP +2. roundtrip accuracy check for the case above: +.IP +cct +proj=pipeline +proj=utm +ellps=GRS80 +zone=32 +step +step +inv +.PP +3. as (1) but specify input columns for longitude, latitude, height and time: +.IP +cct -c 5,2,1,4 +proj=utm +ellps=GRS80 +zone=32 +.PP +4. as (1) but specify fixed height and time, hence needing only 2 cols in input: +.IP +cct -t 0 -z 0 +proj=utm +ellps=GRS80 +zone=32 +.SH HOME PAGE +http://proj4.org/ diff --git a/man/man1/gie.1 b/man/man1/gie.1 new file mode 100644 index 00000000..b444e95b --- /dev/null +++ b/man/man1/gie.1 @@ -0,0 +1,116 @@ +.\" release 5 +.\" +.ad b +.hy 1 +.TH GIE 1 "2018/02/25 Rel. 5.0.0" +.SH NAME +gie \- The Geospatial Integrity Investigation Environment +.SH SYNOPSIS +.B gie +[\-options]... infile... +.SH DESCRIPTION +\fBgie\fR, the Geospatial Integrity Investigation Environment, is a modest +regression testing environment for the PROJ.4 transformation library. +.PP +Its primary design goal was to be able to replace those thousands of +lines of regression testing code that are (at time of writing) part +of PROJ.4, while not requiring any other kind of tooling than the same +C compiler already employed for compiling the library. +.PP +The basic functionality of the gie command language is implemented +through just 3 command verbs: +.PP +operation, which defines the PROJ.4 operation to test, +.br +accept, which defines the input coordinate to read, and +.br +expect, which defines the result to expect. +.PP +E.g: +.PP +operation +proj=utm +zone=32 +ellps=GRS80 +.br +accept 12 55 +.br +expect 691_875.632_14 6_098_907.825_05 +.PP +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. +.PP +By default, gie considers the EXPECTation met, if the result comes to +within 0.5 mm of the expected. This default can be changed using the +"tolerance" command verb (and yes, I know, linguistically speaking, both +"operation" and "tolerance" are nouns, not verbs). See the first +few hundred lines of the "builtins.gie" test file for more details of +the command verbs available (verbs of both the VERBal and NOUNistic +persuation). +.PP +But 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.4 of today. +.PP +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. +.PP +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. +.PP +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). +.PP +While today, we may have more formally well defined metadata systems +(most prominent the OGC WKT2 representation), nothing comes close being +as easily readable ("human compatible") as Gerald's key-value system. +This system in particular, and the PROJ.4 system in general, was +Gerald's great gift to anyone using and/or communicating about geodata. +.PP +It is only reasonable to name a program, keeping an eye on the integrity +of the PROJ.4 system, in honour of Gerald. +.PP +So in honour, and hopefully also in the spirit, of Gerald Ian Evenden +(1935--2016), this is the Geospatial Integrity Investigation Environment. +.SH OPTIONS +.IP "\fB\fB\-h\fR\fR" 1c +Help: print usage information\& +.IP "\fB\fB\-o /path/to/file\fR\fR" 1c +Specify output file name\& +.IP "\fB\fB\-v\fR\fR" 1c +Verbose: Provide non-essential informational output. +Repeat \-v for more verbosity (e.g. \-vv)\& +.IP "\fB\fB\-q\fR\fR" 1c +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)\& +.IP "\fB\fB\-l\fR\fR" 1c +List the PROJ internal system error codes\& +.SH LONG OPTIONS +.IP "\fB\fB\-\-output\fR\fR" 1c +Alias for \-o\& +.IP "\fB\fB\-\-verbose\fR\fR" 1c +Alias for \-v\& +.IP "\fB\fB\-\-help\fR\fR" 1c +Alias for -h\& +.IP "\fB\fB\-\-list\fR\fR" 1c +Alias for \-l\& +.SH EXAMPLES +1. Run all tests in file \"corner-cases.gie\", providing much extra information +.IP +gie \-vvvv corner-cases.gie +.PP +2. Run all tests in files \"foo\" and \"bar\", providing info on failures only +.IP +gie foo bar +.SH HOME PAGE +http://proj4.org/ |