[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. Introduction

GNU Gama is a project 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


and the project is hosted on


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, and is simply used by GNU Gama.

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 an 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

The collection of sample networks is available separetely. To clone the gama-local examples from GIT use the command

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 bin. 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

$ ./configure
$ 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 a git server), you have to generate it using auxiliary script autogen.sh. To compile and build all binaries. Run

$ ./configure [--bindir=DIR --infodir=DIR]
$ make install

if you want also to install the binaries. You can use configure parameters if you need to change directories where user executables and info documentation should be installed.

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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
$ cd build
$ cmake ..
$ make

where build is an arbitrary directory name for out-of-place build.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.2 Precompiled binaries for Windows

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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) or for MS Windows (tested with Borland compiler from Borland free command line tools and with Microsoft Visual C++ compiler; support for Windows platform is currently limited to maintaing compatibility with the two mentioned compilers).

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, input file name with extension.txt is used. If development files for Sqlite3 (package libsqlite3-dev) are installed during the build, gama-local also supports reading adjustment input data from an sqlite3 database. If run without arguments gama-local prints a short help

$ ./gama-local

Adjustment of local geodetic network        version: 2.00 / GNU g++

Usage: gama-local  input.xml  [options]
       gama-local  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]


--algorithm  svd | gso | 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
--angles     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)

Program gama-local version is followed by information on compiler used to build the program (apart from GNU g++ compiler, two other possibilities are bcc and msc for Borland and Microsoft compilers respectively, when build under Microsoft Windows).

Option --algorithm enables to select numerical method used for solution of the adjustment. Implicitly is used Singular Value Decomposition (svd), alternatively user can decide for block matrix algorithm GSO by Frantisek Charamza, based on Gram-Schmidt orthogonalization. In both these cases, project equations are solved directly without forming normal equations. Third possibility is to select Cholesky decomposition of semidefinite matrix of normal equations (cholesky).

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 --angles 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.

Adjustment results (--text, --xml) and others can be 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 --octave is used to output simplified adjustment results for GNU Octave; only points’ names (identifiers), adjusted coordinates with indexes and corresponding covariances are given in the .m file.

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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


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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 and Greg Troxel.

Václav Petráš is the author of SQL schema, SQLite and gama-local.

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Ales Cepek on May 13, 2018 using texi2html 1.82.