1. Introduction

GNU Gama package is dedicated to adjustment of geodetic networks. It is intended for use with traditional geodetic surveyings which are still used and needed in special measurements (e.g., underground or high precision engineering measurements) where the Global Positioning System (GPS) cannot be used.

In general, surveying is the technique and science of accurately determining the terrestrial or three-dimensional spatial position of points and the distances and angles between them.(1)

Adjustment is a technical term traditionally used by geodesists and surveyors which simply means “application of the least squares method to process the over-determined system of measurements” (statistical methods other than least squares are used sometimes but are not common). In other words, we have more observations than needed and we are trying to get the best estimate for adjusted observations and/or coordinates.

Adjustment of geodetic networks means that we have a set of fixed points with given coordinates, a set of points with unknown coordinates (possibly with approximate values available) and a set of observations among them. What is typical of adjustment of special geodetic measurements is that the resulting linearized system might be singular (we can have a network with no fixed points) and we are not only interested in the values of ‘adjusted parameters and observations’ but also in the estimates of their covariances. This is what Gama does.

Gama was originally inspired by Fortran system Geodet/PC (1990) designed by Frantisek Charamza. The GNU Gama project started at the department of mapping and cartography, faculty of Civil Engineering, Czech Technical University in Prague (CTU) about 1998 and its name is an acronym for geodesy and mapping. It was presented to a wider public for the first time at FIG Working Week 2000 in Prague and then at FIG Workshop and Seminar at HUT Helsinki in 2001.

The GNU Gama home page is

http://www.gnu.org/software/gama/

and the project is hosted on

http://savannah.gnu.org/git/?group=gama

GNU Gama is released under the GNU General Public License and is based on a C++ library of geodetic classes and functions and a small C++ template matrix library matvec. For parsing XML documents GNU Gama calls the expat parser version 1.1, written by James Clark. The expat parser is not part of the GNU Gama project, but it is used by the project.

Adjustment in local Cartesian coordinate systems is fully supported by a command-line program gama-local that adjusts geodetic (free) networks of observed distances, directions, angles, height differences, 3D vectors and observed coordinates (coordinates with given variance-covariance matrix). Adjustment in global coordinate systems is supported only partly as a gama-g3 program.

1.1 Download

GNU Gama can be found in the subdirectory /gnu/gama/ on your favourite FTP GNU mirror or cloned from the GIT. See our project page at savannah for more information.

To get anonymous read-only access to the GIT repository for the latest GNU Gama source, issue the following command

git clone git://git.sv.gnu.org/gama.git

1.2 Install

GNU Gama is developed and tested under GNU/Linux. A static library libgama.lib and executables are build in folders lib and src. You can compile Gama easily yourself if you download the sources from a FTP server. The preferred way is to have expat XML parser installed on your system, if not, GNU Gama will be build with internally stored expat older source codes version 1.1.

Change to the directory of Gama project and issue the following commands at the shell prompt (with some optional parameters)

$ ./configure [--enable-extra-tests --bindir=DIR --infodir=DIR]
$ make

For GNU Gama test suite run

$ make check

If the script configure is not available (which is the case when you download source codes from the git server), you have to generate it using auxiliary script autogen.sh. To compile and build all binaries. Run

$ ./autogen.sh
$ ./configure

and

$ make install [--prefix=/your/prefered/install/directory]

if you also want to install executables and info documentation.

Typically, if you want to download (see section Download) and compile sources, you will run following commands:

$ git clone git://git.sv.gnu.org/gama.git gama
$ cd gama
$ ./autogen.sh
$ ./configure
$ make

You should have expat XML parser and SQLite library already installed on your system. For example to be able to compile Gama on Ubuntu 10.04 you have to install following packages:

make doxygen git automake autoconf libexpat1-dev libsqlite3-dev

To compile user documentation in various formats (PDF, HTML, …) run the following commands

$ cd doc/
$ make download-gendocs.sh
$ make run-gendocs.sh

The documentation should be in doc/manual directory. To compile API documentation run

$ doxygen

in your gama directory. Doxygen output will be in the doxygen directory.

1.2.1 CMake

Alternatively you can use CMake to generate makefiles for Unix, Windows, Mac OS X, OS/2, MSVC, Cygwin, MinGW or Xcode. Configuration file CMakeLists.txt is available from the root distribution directory. For example to build gama-local binary for Linux run

$ mkdir build_dir
$ cd build_dir
$ cmake .. [ -G generator-name ]
$ make --build .

where build_dir is an arbitrary directory name for out-of-place build and optional generator-name specifies a build system generator, for example Ninja.

1.2.2 pkgsrc

pkgsrc is a framework for managing third-party software on UNIX-like systems, currently containing over 26,000 packages. It is the default package manager of NetBSD and SmartOS, and can be used to enable freely available software to be built easily on a large number of other UNIX-like platforms. The binary packages that are produced by pkgsrc can be used without having to compile anything from source. It can be easily used to complement the software on an existing system.

Gama is available via pkgsrc as geography/gama, see https://www.pkgsrc.org/ for more information.

1.2.3 Precompiled executables for Windows

qgama is a Qt application for adjustment of geodetic networks with database support, where the database can be a simple SQLite3 flat file, used for storing geodetic network data, or any full-featured relational DBMS with Qt driver available like PostgreSQL or MySQL. It is build on the GNU gama adjustment library.

Windows executable qgama.exe with all DLL libraries is available from the GNU FTP server

https://ftp.gnu.org/gnu/gama/windows/

together with command-line interface executables gama-local.exe and gama-g3 in the subdirectory bin.

1.3 Program gama-local

Program gama-local is a simple command line tool for adjustment of geodetic free networks. It is available for GNU Linux (the main platform on which project GNU Gama is being developed), BSD or Windows.

Program gama-local reads input data in XML format (XML input data format for gama-local) and prints adjustment results into ASCII text file. If output file name is not given, adjustment results in XML format are sent to the standard output device. If development files for Sqlite3 (package libsqlite3-dev) are installed, gama-local also supports reading adjustment input data from sqlite3 database. When run without arguments gama-local [--help] prints a review of runtime options

Adjustment of local geodetic network        version: 2.29
************************************
https://www.gnu.org/software/gama/

Usage: gama-local  [--input-xml] input.xml  [options]
       gama-local  [--input-xml] input.xml  --sqlitedb sqlite.db  --configuration name  [options]
       gama-local  --sqlitedb sqlite.db  --configuration name  [options]
       gama-local  --sqlitedb sqlite.db  --readonly-configuration name  [options]

Options:

--algorithm  gso | svd | cholesky | envelope
--language   en | ca | cz | du | es | fi | fr | hu | ru | ua | zh
--encoding   utf-8 | iso-8859-2 | iso-8859-2-flat | cp-1250 | cp-1251
--angular    400 | 360
--latitude   <latitude>
--ellipsoid  <ellipsoid name>
--text       adjustment_results.txt
--html       adjustment_results.html
--xml        adjustment_results.xml
--octave     adjustment_results.m
--svg        network_configuration.svg
--cov-band   covariance matrix of adjusted parameters in XML output
             n  = -1  for full covariance matrix (implicit value)
             n >=  0  covariances are computed only for bandwidth n
--iterations maximum number of iterations allowed in the linearized
             least squares algorithm (implicit value is 5)
--export     updated input data based on adjustment results
--verbose    [yes | no]
--version
--help

Report bugs to: <bug-gama@gnu.org>
GNU gama home page: <https://www.gnu.org/software/gama/>
General help using GNU software: <https://www.gnu.org/gethelp/>

Program version is followed by information on compiler used to build the program (apart from GNU g++ compiler other possibilities are Clang, Intel C++ compiler and Visual C++, when build under Microsoft Windows).

Program gama-local can read XML input from the standard input if you put "-" (hyphen) after the option --input-xml. This option is special because it is optional (you can specify XML input file name or "-" without it). Elective --input-xml enables backward compatibility with the usage of older versions.

Adjustment results (--text, --xml) and others can be similarly redirected to standard output if instead of a file name is used "-" string. If no output is given, XML adjustment format is implicitly send to standard output.

Option --algorithm enables to select numerical method for solution of the adjustment. Implicit algorithm is sparse matrix envelope. Another possibilities are Cholesky decomposition of semidefinite matrix of normal equations (cholesky), block matrix algorithm GSO by Frantisek Charamza based on Gram-Schmidt orthogonalization (gso) and Singular Value Decomposition (svd). In the last two cases (gso and svd) project equations are solved directly without forming normal equations.

Option --language selects language used in output protocol. For example, if run with option --language cz, gama-local prints output results in Czech languague using UTF-8 encoding. Implicit value is en for output in English.

Option --encoding enables to change inplicit UTF-8 output encoding to iso-8859-2 (latin-2), iso-8859-2-flat (latin-2 without diacritics), cp-1250 (MS-EE encoding) cp-12251 (Russian encoding).

Option --angular selects angular units to be used in output.

Options --latitude and/or --ellipsoid are used when observed vertical and/or zenith angles need to be transformed into the projection plane. If none of these two options is explicitly used, no corrections are added to horizontal and/or zenith angles. If only one of these options is used, then implicit value for --latitude is 45 degrees (50 gons) and implicit ellipsoid is WGS84. Mathematical formulas for the corrections is given in the following section.

Option --octave is used to output simplified adjustment results for GNU Octave, i.e. in an .m file. The following information is give in the output file

• general adjustment paramameters (number of unknowns, observetions etc.)
• list of fixed points’ ids (may be empty)
• adjustment points; ids
• adjustment indexes of unknouwns
• indexes of constrained coordinates (subset of adjustment indexes)
• approximate and adjusted coordinates (zero if not available)
• full covariance matrix of adjusted coordinates
• sparse design matrix, rhs and weights (Ax = b, P = inv(C_ll))
• and adjustment results in matrix format

In the case of free networks system of normal equations is augmented with matrix of constrains. Adjustmment can be then computed independetly in Octave and compared with results from Gama for unknown coordinates. We suggest that for comaprision of Gama and Octave results number of itereations is set to zero (--iterations 0).

This Octave output is currently available only for algorithm envelope (Gama version 2.10), also adjustment in Octave is not supported for the special case of one fixed point and one constrained (where normal equation cannot be directly augmented with constraints because of different number of unknowns).

Option --cov-band is used to reduce the number of computed covariances (cofactors) in XML adjustment output. Implicitly full matrix is written to XML output, which could degrade time efficiency for the envelope algorithm for sparse matrix solution. Explicit option for full covariance matrix is --cov-band -1, option --cov-band 0 means that only a diagonal of covariance matrix is written to XML output, --cov-band 1 results in computing the main diagonal and first codiagonal etc. If higher rank is specified then available, it is reduced do maximum possible value dim-1.

Option --iterations enables to set maximum number of iterations allowed in the linearized least squares algorithm. After the adjustment gama-local computes differences between adjusted observations computed from residuals and from adjusted coordinates. If the positional difference is higher than 0.5mm, approximate coordinates of adjusted points are updated and the whole adjustment is repeated in a new iteration. Implicit number of iterations is 5.

1.3.1 Reductions of horizontal and zenith angles

For evaluating of reductions of horizontal and zenith angles, gama-local computes a helper point P_1 in the center of the network. Horizontal and zenith angles observed at point P_2 are transformed to the projection plane perpendicular to the normal z_1 of the helper point P_1. Coordinates (x_2, y_2) of point P_2 are conserved, but its normal z_2 is rotated by the central angle 2\gamma_12 to be parallel with z_1.

Formulas for reductions of horizontal and zenith angles are given only in the printed version.

1.4 Reporting bugs

Undoubtedly there are numerous bugs remaining, both in the C++ source code and in the documentation. If you find a bug in either, please send a bug report to

bug-gama@gnu.org

We will try to be as quick as possible in fixing the bugs and redistributing the fixes. If you prefere, you can always write directly to Aleš Čepek.

1.5 Contributors

The following persons (in chronological order) have made contributions to GNU Gama project: Aleš Čepek, Jiří Veselý, Petr Doubrava, Jan Pytel, Chuck Ghilani, Dan Haggman, Mauri Väisänen, John Dedrum, Jim Sutherland, Zoltan Faludi, Diego Berge, Boris Pihtin, Stéphane Kaloustian, Siki Zoltan, Anton Horpynich, Claudio Fontana, Bronislav Koska, Martin Beckett, Jiří Novák, Václav Petráš, Jokin Zurutuza, 项维 (Vim Xiang), Tomáš Kubín, Greg Troxel, Kristian Evers, Oleg Goussev, Petra Millarová, Jan Holešovský and Friedhelm Krumm.

Jiří Veselý is the author of calculation of approximate coordinates by intersections and transformations (class Acord). Václav Petráš is the author of SQL schema, SQLite and gama-local. Petra Millarová is the main author of class Acord2 and other helper classes for combinatorial solution of medians of approximate coordinates.

Friedhelm Krumm, Geodätisches Institut Universität Stuttgart, contributed numerical examples for the adjustment of geodetic networks (1D, 2D and 3D) published in his Geodetic Network Adjustment Examples, Rev. 3.5, January 20, 2020. https://www.gis.uni-stuttgart.de/ In version 2.18 the format of input data used in his Examples was implemented in GNU Gama and is used in command line conversion program gama-local-krumm2xml and also directly in qgama GUI.

This document was generated on February 17, 2024 using texi2html 1.82.