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.

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