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
points with given coordinates coordinates of some points and a set of
observations among them. What is typical of adjustment of special
geodetic measurements is that the resulting linearised 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.

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.

1.2 Install

GNU Gama is developed and tested under Debian GNU/Linux
(http://www.debian.org/). 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. If expat XML parser is installed on your system,
change to the directory of Gama project and issue the following
commands at the shell prompt

$ ./configure
$ make

To run tests from the Gama test suite try

$ 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:

1.2.1 Precompiled binaries for Windows

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

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.

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 and --xml) 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 --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.

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.

2. XML input data format for gama-local

The input data format for a local geodetic network adjustment (program
gama-local) is defined in accordance with the definition of Extended
Markup Language (XML) for description of structured data.
The XML definition can be found at

Input data (points, observations and other related information) are
described using XML start-end pair tags <xxx> and </xxx>
and empty-element tags <xxx/>.

The syntax of XML gama-local input format is described in XML
schema (XSD), the file gama-local.xsd is a part of the
GNU gama distribution and can formally be validated
independently on the program gama-local, namely in unit testing
we use xmllint validating parser, if it is installed.

For parsing the XML input data, gama-local uses the XML parser
Expat copyrighted by James Clark which is described at

Expat is subject to the Mozilla Public License (MPL), or may
alternatively be used under the GNU General Public License (GPL)
instead.

In the gama-local XML input, distances are given in meters,
angular values in centigrades and their standard deviations (rms
errors) in millimeters or centigrade seconds, respectively.
Alternatively angular values in gama-local XML input can be
given in degrees and seconds (see section Angular units). At the end of
this chapter an example of the gama-local XML input data
object is given.

2.1 Angular units

Horizontal angles, directions and zenith angles in gama-local
XML adjustment input are implicitly given in gons and their standard
deviations and/or variances in centicentigons. Gon, also called
centesimal grade and Neugrad (German for new grad), is 1/400-th of the
circumference. For example

<direction from="202" to="416" val="63.9347" stdev="10.0" />

The same angular value (direction) can be expressed in degrees as

<direction from="202" to="416" val="57-32-28.428" stdev="3.24" />

In XML adjustment input degrees are coded as a single string, where
degrees (57), minutes (32) and seconds (28.428) are separated by
dashes (-) with optional leading sign. Spaces are not allowed inside
the string. Gons and degrees may be mixed in a single XML document but
one should be careful to supply the information on standard deviations
and/or covariances in the proper corresponding units.

Internally gama-local works with gons but output can be
transformed to degrees using the option --angles 360.

2.2 Prologue

XML documents begin with an XML declaration that specifies the version
of XML being used (prolog). In the case of gama-local
follows the root tag <gama-local> with XML Schema namespace
defined in attribute xmlns:

2.3 Tags <gama-local> and <network>

A pair tag <gama-local> contains a single pair tag <network>
that contains the network definition. The definition of the network is
composed of three sections:

<description> of the network (annotation or comments),

network <parameters /> and

<points-observations> section.

The sections <description> and <parameters /> are
optional, the section <points-observations> is mandatory. These
three sections may be presented in any order and may be repeated several
times (in such a case, the corresponding sections are linked
together by the software).

The pair tag <network> has two optional attributes axes-xy
and angles. These attributes are used to describe orientation of
the xy orthogonal coordinate system axes and the orientation of the
observed angles and/or directions.

Many geodetic systems are right handed with x axis oriented
east, y axis oriented north and counterclockwise angular
observations. Example of left-handed orthogonal system with different
axes orientation is coordinate system Krovak used in the Czech
Republic where the axes x and y are oriented south and
west respectively.

GNU Gama can adjust any combination of coordinate and angular
systems.

2.4 Network description

The description of a geodetic network is enclosed in the start-end pair
tags <description>. Text of the description is copied into the
adjustment output and serves for easier identification of results. The
text is not interpreted by the program, but it may be helpful for users.

Example

<description>
A short description of a geodetic network ...
</description>

update-constrained-coordinates = "no" enables user to control
if coordinates of constrained points are updated in iterative
adjustment. If test on linerarization fails (see section Test on linearization),
Gama tries to improve approximate coordinates of adjusted points and
repeats the whole adjustment. Coordinates of constrained points are
implicitly not changed during iterations.

cov-band = "-1" the bandwith of covariance matrix of the
adjusted parameters in the output XML file (-1 means all covariances).

Values of the attributes must be given either in the double-quotes
("…") or in the single quotes ('…'). There
can be white spaces (spaces, tabs and new-line characters)
between attribute names, values, and the equal sign.

With exception of the first attribute (point id), all other
attributes are optional. Decimal numbers can be used as needed.

Control coordinates marked using the fix parameter are not
changed in the adjustment. Uppercase and lowercase notation of
coordinates with the fix parameter are interpreted the same.
Corrections are applied to the unknown parameters identified by
coordinates written in lowercase characters given in the adj
parameter. When the coordinates are written using uppercase, they are
interpreted as constrained coordinates. If coordinates are marked
with both the fix and adj, the fix parameter will
take precedence.

Constrained coordinates are used for the regularization of free
networks. If the network is not free (fixed network), the
constrained coordinates are interpreted as other unknown
parameters. In classical free networks, the constrained points
define the regularization constraint

\sum dx^2_i+dy^2_i = \min.

where dx and dy are adjusted coordinate corrections and
the summation index i goes over all constrained points.
In other words, the set of the constrained points defines the
adjustment of the free network (its shape and size) with a
simultaneous transformation to the approximate coordinates of selected
points. Program gama-local allows the definition of
constrained coordinates with 1D leveling networks, 2D and 3D local
networks.

Example

2.8 Set of observations

The pair tag <obs> groups together a set of observations which
are somehow related. A typical example is a set of directions and
distances observed from one stand-point. An observation section
contains a set of

horizontal directions <direction … />

horizontal distances <distance … />

horizontal angles <angle … />

slope distances <s-distance … />

zenith angles <z-angle … />

azimuths <azimuth … />

height differences <dh />

The band variance-covariance matrix of directions, distances, angles
or other observations
listed in one <obs> section may be supplied using a
<cov-mat> pair tag with attributes dim (dimension) and
band (bandwidth). The band-width of the diagonal matrix is equal
to 0 and a fully-populated variance-covariance matrix has a bandwidth of
dim-1.

Observation variances and covariances (i.e. an upper-symmetric part of
the band-matrix) are written row by row between <cov-mat> and
</cov-mat> tags. If present, the dimension of the
variance-covariance matrix must agree with the number of observations.

The following example of variance-covariance matrix with dimension 6 and
bandwidth 2 (two nonzero codiagonals and three zero codiagonals)

If two or more sets of directions with different orientations are
observed from a stand-point, they must be placed in different <obs>
sections. The value of an orientation angle can be explicitly stated
with an attribute orientation="…". Normally, it is more
convenient to let the program calculate approximate values of
orientations needed for the adjustment. If directions are present, then
the attribute station must be defined.

Optional attribute from_dh="…" enables to enter implicit
height of instrument for all observations within the <obs> pair
tag.

Observed distances are expressed in meters, their standard deviations in
millimeters. Observed directions and angles are expressed in centigrades
(400) and their standard deviations in centigrade seconds.

Height differences can be entered in the <obs> or
<height-differences> section. If entered in the <obs> section,
the dist="..." parameter is ignored (Height differences).

The standard deviation is an optional attribute. However since all
observations in the adjustment must have their weights defined, the
standard deviation must be given either explicitly with the attribute
stdev="…" or implicitly with <points-observation
direction-stdev="…" > or with a variance-covariance matrix for
the given observation set. A similar approach applies to all the
observations (distances, angles, etc.)

Contrary to directions, distances in an observation set
(<obs>) do not need to share a common stand-point. An example is
set of distances observed from several stand-points with
a common variance-covariance matrix.

Example

2.14 Azimuths

The azimuth is defined in GNU Gama as an observed horizontal angle
measured from the North to the given target. The true north
orientation is measured by gyrotheodolites, mainly in mine
surveying. In Gama azimuths’ angle can be measured clockwise or
counterclocwise according to the angle orientation defined in
<parameters /> tag.

Azimuths are expressed with the following attributes in an
empty-element tag <azimuth />

The standard deviation is an optional attribute. However since all
observations in the adjustment must have their weights defined, the
standard deviation must be given either explicitly with the attribute
stdev="…" or implicitly with <points-observation
azimuth-stdev="…" > or with a variance-covariance matrix for
the given observation set.

Example

2.15 Height differences

A set of observed leveling height differences is described using the
start-end tag <height-differences> without parameters. The
<height-differences> tag can contain a series of height
differences (at least one) and can optionally be supplied with a
variance-covariance matrix. Single height differences are defined with
empty tags <dh /> having the following attributes:

from = "…" standpoint identification

to = "…" target identification

val = "…" observed leveling height difference

stdev = "…" standard deviation of levellin elevation and

dist = "…" distance of leveling section (in kilometers)

If the value of standard deviation is not present and length of
leveling section (in kilometres) is defined, the value of standard
deviation is computed from the formula

m_dh = m_0 sqrt(D_km)

If the value of standard deviation of the height difference is defined,
information on leveling section length is ignored. A third
possibility is to define a common variance-covariance matrix for all
elevations in the set.

2.16 Control coordinates

Control (known) coordinates are described by the start-end pair tag
<coordinates>. A series of points with known coordinates can be
defined using the <point /> tag. The variance-covariance matrix
for the entire set of points can be created with a single
<cov-mat> tag. In the <point /> tags, a point
identification (ID) and its coordinates (x, y and z) must be listed.
Although the order of the <point /> tag attributes is irrelevant
in the corresponding variance-covariance matrix, the expected order of
the coordinates is x, y and z (the horizontal coordinates x, y, or the
height z might be missing, but not both). The type of the points may be
defined either directly within the <coordinates> tag or outside
of it.

2.17 Coordinate differences (vectors)

Observed coordinate differences describe relative positions of station
pairs (vectors). Contrary to the observed coordinates, the
variance-covariance matrix of the coordinate differences always
describes all three elements of the 3D vectors.

3.3 Network SQL definition

Network definitions are stored in the configurations table.
This table contains all parameters for each network such as value of a
priori reference standard deviation or orientation of the xy
orthogonal coordinate system axes.

It is obvious that in one database file can be stored more networks
(configurations).

Configuration descriptions (annotation or comments) are stored separately
in table descriptions.
The description is split to many records because of compatibility with various
databases (not all databases implements type TEXT).

Field (attribute) conf_id identifies a configuration in the database.
Field conf_name is used to identify configuration outside the database
(e.g. parameter in command-line when reading data from database
to gama-local).

update_cc enables user to control
if coordinates of constrained points are updated in iterative
adjustment. If test on linerarization fails (see section Test on linearization),
Gama tries to improve approximate coordinates of adjusted points and
repeats the whole adjustment. Coordinates of constrained points are
implicitly not changed during iterations.
Acceptable values are yes, no, default value
is no.

epoch
is measurement epoch.
It is floating point number
(default value is 0.0).

algorithm
specifies numerical method used for solution of the adjustment.
For Singular Value Decomposition set value to svd.
Value gso stands for block matrix algorithm GSO by Frantisek Charamza
based on Gram-Schmidt orthogonalization,
value cholesky for Cholesky decomposition of semidefinite matrix
of normal equations
and value envelope for a Cholesky decomposition with
envelope reduction of the sparse matrix.
Default value is svd.

ang_units
Angular units of angles in gama-local output.
Value 400 stands for gons and value 360 for degrees
(default value is 400).
Note that this doesn’t effect units of angles in database.
For further information about angular units see Angular units.

3.4 Table points

conf_id
is id of configuration which points belongs to.

id
identifies point in a database and also in an output.
It is mandatory and it is character string (SQL type is VARCHAR(80)).
Point id has to be unique within one configuration.
In documentation it is referred as point identification or point id.

x, y and z
coordinates of a point.
Coordinate z is considered as height.

txy and tz
specify the type of coordinates x, y and z.
Acceptable values are fixed, adjusted and constrained
(there is no default value).
For details see Points.

3.5 Table clusters

The cluster is a group of observations with the common covariance matrix.
The covariance matrix allows to express any combination of correlations
among observations in cluster (including uncorrelated observations,
where covariance matrix is diagonal).
For explanation see Observation data and points.

In the database observations are stored in three tables:
obs, coordinates and vectors.
Cluster’s covariance matrix is stored in table covmat.
Every observation, vector or coordinate in database has to be in some cluster.

conf_id
is id of configuration which cluster belongs to.

ccluster
identifies a cluster within one configuration.

dim and band
specify dimension and bandwidth of covariance matrix.
The bandwidth of the diagonal matrix is equal to 0 and a
fully-populated covariance matrix has a bandwidth of dim-1
(band maximum possible value is dim-1).

tag
specifies type of observations in cluster which also implies the table
where they are stored in.
obs and height-differences stand for obs table,
coordinates and vectors stand for coordinates table
and vectors table respectively.

Observations, vectors and coordinates are identified by
configuration id (conf_id), cluster id ccluster
and theirs index (indx).
Observation index (indx) has to be unique within observations
of one cluster (which belongs to one configuration).
The same applies for vectors and coordinates.

3.10 Example of local geodetic network in SQL

Providing complete example would be reasonable because of its extent.
However, you can obtain example by following these instructions:

Create a file with XML representation of network by copy and paste example
from Example of local geodetic network to a new file.
Note that file should start with <?xml version="1.0" ?> (no whitespace).
Alternatively you can use existing XML file from collection of sample networks
(see Download).
Then you can convert your XML file (here example_network.xml)
to SQL statements by program gama-local-xml2sql
(the path depends on your Gama installation).

4. Network adjustment with gama-local

Adjustment of local geodetic network is a classical case of
adjustment of indirect observations. After estimation of
approximate values of unknown parameters (coordinates of points) and
linearization of functions describing relations between observations and
parameters we solve linear system of equations

(1) Ax = b + v,

where A is coefficient matrix, b is vector of absolute terms
(right hand side) and v is vector of residuals.
This system is (generally) overdetermined and we seek
the solution x satisfying the basic criterion of Least Squares

(2) v'Pv = min,

where P is weight matrix. This criterion unambiguously
defines the shape of adjusted network.

In the case of free network the system (1)
is singular (matrix A has linearly dependent columns)
and we have to define second regularization criterion

(3) \sum x_i^2 = min, for all selected i

stating that at the same time we demand that the sum of squares
corrections of selected parameters is minimal (corrections of unknown
parameters with indexes from the set
of all selected unknowns.
Geometrically this criterion is equivalent to adjustment of the network
according to (2) with simultaneous transformation to the selected set of
fiducial points. This transformation does not change the shape of
adjusted network.

Often it is advantageous to work with a homogenized system,
ie. with the system of project equations in which coefficient of each
row and absolute term are multiplied by square root of the weight of
corresponding observation.

4.1 Approximate coordinates

For computation of coefficients in system (1) (ie. during
linearization) we need, first of all, an estimate of approximate
coordinates of points and approximate values of orientations of observed
directions sets.

Approximate values of unknown parameters are usually not known and we
have to compute them from the available observations. For approximate
value of orientation program gama-local uses median of all estimates
from the given set of directions to the points with known coordinates.
Median is less sensitive to outliers than arithmetic mean which is
normally used for approximate estimate of orientations

During the phase of computation of approximate coordinate of points,
program gama-local walks through the list of computed points
and for each point gathers all determining elements pointing to
points with known or previously computed coordinates.
Determining elements are

outer bearing (oriented half-line) starting from the point
with known coordinates and pointing to the computed point

distance between given and computed points

inner angle with vertex in the computed point and arms
intersecting given points

For all combinations of determining elements program gama-local
computes intersections and estimates approximate coordinates as the
median of all available solutions.

If at least one point was resolved while iterating through the list,
the whole cycle is repeated.

If no more coordinates can be solved using intersections and points with
unknown coordinates are remaining, program tries to compute coordinates
of unresolved points in a local coordinates system and obtain their
coordinates using similarity transformation. If a transformation
succeeds to resolve coordinates at least one computed point and there
are still some points without coordinates left, the whole process is
repeated. Classes for computation of approximate coordinates have been
written by Jiri Vesely.

If program gama-local fails to compute approximate coordinates
of some of the network points, they are eliminated from the
adjustment and they are listed in the output listing.

With the outlined strategy, program gama-local is able to estimate
approximate coordinates in most of the cases we normally meet in
surveying profession. Still there are cases in which the solution fails.
One example is an inserted horizontal traverse with sets of observed
direction on both ends but without a connecting observed distance. The
solution of approximate coordinates can fail when there is a number of
gross error for example resulting from confusion of point
identifications but in normal situations, leaving computation of
approximate coordinates on program gama-local is recommended.

4.2 Gross absolute terms

One of parameters in XML input of program gama-local is tolerance
tol-abs for detecting of gross absolute terms in
project equations. Observations with outlying absolute terms
are always excluded from adjustment.

We can choose only the type of actual reference standard deviation
(m0 or m0’) but not its value. The value corresponds
to a priori given value of reference standard deviation
or to the results of adjustment. On the type of actual reference
standard deviation depends the choice of density functions
of stochastic quantities in statistical analysis of the adjustment.

A priori reference standard deviation m0 is used in the
cases when we know its value in advance and with sufficient reliability.
Another situation when m0 is used are networks with low number of
degrees of freedom (poorly overdetermined systems) or when veen degrees
of freedom is zero. Examples may be analysis of network models etc.

A posteri estimate of reference standard deviation m0’ is
used in cases when a priori value of reference standard deviation
m0 is not known and when degrees of freedom is sufficiently high
and reliable for empirical estimate of m0’.

The standard deviantion of an adjusted quuantity is computed in
dependence of the choice of actual type of reference standard deviation
m0_a according to formula

m0_a sqrt(q)

where q is the weight coefficient of the corresponding adjusted
unknown parameter or observation. Apart from the standard deviation,
program gama-local computes for the adjusted quantity its confidence
interval in which its real value is located with the probability
P.

4.4 Test on the reference standard deviation

and a priori reference standard deviation m0 (input data parameter
m0-apr). For given significance level alpha lower and
upper bounds of interval (L, U) are computed so, that if
hypothesis H_0 is true, probabilities P(m0’/m0
le D) and P(m0’/m0 ge H) are equal to
alpha/2. Lower and upper bounds of the interval are computed as

L = sqrt((Chi^2_{1-alpha/2,r})/r),
U = sqrt((Chi^2_{ alpha/2 ,r})/r).

Probability

P(L < m0'/m0 < U) = conf-pr

is by default 95%, this corresponds to 5% confidence level test.

Exceeding the upper limit H of the confidence interval can be
caused even by a single gross error (one outlying observation).
Method of Least Squares is generally very sensitive to presence of
outliers. Safely can be detected only one observation whose elimination
leads to maximal decrease of a posteriori estimate of reference standard
deviation

(6) m0'' = sqrt{(v'P v - delta)/(r-1)},
delta = max(v_i^2/q_vi),

where

(7) q_vi = 1/p_i - q_Li

is weight coefficient of i-th residual. If the set of
observations contains only one gross error, the outlying observation is
likely to be detected, but this can not be guaranteed.

In addition, program gama-local computes a posteriori estimate
of reference standard deviation separately for horizontal distances
and directions and/or angles after formula from

4.5 Information on points

Program gama-local lists separately review of coordinates of fixed and
adjusted points; adjusted constrained coordinates are marked with
*; see equation (3). Adjusted coordinate standard deviations
m_x and m_y, and values for computing confidence intervals
are given in the listing of adjusted coordinates (Parameters of statistical analysis). In the review index i is the index of unknown
x_i from the system of project equations (1) corresponding to the
point coordinates x and y.

The angle alpha (the bearing of semimajor axis) is measured
clockwise from X axis.

Probability that standard ellipse covers real position of a point is
relatively low. For this reason program gama-local computes extra
confidence ellipse for which the probability of covering real
point position is equal to the given confidence probability. Both
ellipsy are located in the same center, they share the same bearing of
semimajor axes and they are similar. For lengths of their semi-axis
holds

symbol delta is used for correction of approximate coordinates
and alpha is bearing of confidence ellipse semimajor axis.

If network contains sets of observed directions, program writes
information on corresponding adjusted orientations, standard deviations
and confidence intervals. Index i is the same as in the case of
adjusted coordinates the index of i-th adjusted unknown in the
project equations.

4.6 Adjusted observations and residuals

In the review of adjusted observations program gama-local prints index of
the observation, index of the row in matrix A in the system (1),
identifications of standpoint and target point, type of the observation,
its approximate and adjusted value, standard deviation and confidence
interval.

Review of residuals serves for analysis of observations and containts
values of normalized or studentized residuals (depending on type of
m0_a used) and three characteristics.
Theese are coefficient f identifying weak network elements and
estimates of real error of observation e-obs and real error of
its adjusted value e-adj, see definition in the following text.

If normalized or studentized residual exceeds critical value for the
given confidence probability, it is marked in the review with symbol
c (critical) and maximal normalized or studentized residual is
marked with symbol m.

4.7 Identification of weak network elements

When planning observations in a geodetic network we always try to
guarantee that all observed elements are checked by other measurements.
Only with redundant measurements it is possible to adjust observations
and possibly remove blunders that might otherwise totaly corrupt
the whole set of measurements. Apart from sufficient number of redundant
observations the degree of control of single observed elements
is given by the network configuration, ie. its geometry.

Less controlled observations represent weak network elements and
they can in extreme cases even disable detection of gross
observational errors as it is in the case of uncontrolled
observations. There are two limit cases of observation control

fully controlled observation as is for example an observed
distance between two fixed points (standard deviation of the adjusted
element is zero; standard deviation of the residual equals to the
standard deviation if the observation) and

uncontrolled observations as is a free polar bar for example
(standard deviation of adjusted value is equal to standard deviation of
observed quantity; residual and standard deviation of the residual are
zero).

Weakly controlled or uncontrolled observations can result even from
elimination of certain suspisios observations during analysis of
adjusment.

Standard deviation of adjusted observations is less
than standard deviation of the measurement.
Degree of observation control in network
is defined as coefficient

(8) f = 100 (m_l - m_L)/m_l,

where
m_l
is standard deviation of observed quantity and m_L is standard
deviation computed from a posteriori reference standard deviation
m0. We consider observed network element to be

4.8 Estimation of real errors

Acording to previous section we can consider an observation to be
controlled if its coefficient f > 0.1. Any controlled
observation can be eliminated from the network without corrupting the
network consistency—network reduced by one controlled observation can
be adjusted and all unknown parameters can be compute without the
eliminated observation.

Estimate of real error of i-th observation is defined as

(9) e_li = L^red_i - l_i,

where
e_li
is value of i-th observation and
is value of i-th network element computed from adjusted
coordinates and/or orientations of the reduced network. Similarly is
defined the estimate of real error of a residual

(10) e_vi = L^red_i - L_l.

Adjustment results are the best statistical estimate of unknown
parameters that we have. This holds true even for adjustment of
reduced network which is not influenced by real error of
i-th observation. On favourable occasions differences (9) and
(10) can help to detect blunders but to interpret these estimates as
real errors is possible only with substantial exaggeration.
These estimates fail when there are more than one significant
observational error. Generally holds tha the weaker the element is
controlled in netowrk the less reliable these estimates are.

Estimate of real error of an observation computes program gama-local as

4.9 Test on linearization

Mathematical model of geodetic network adjustment in gama-local
is defined as a set of known real-valued differentiable functions

(11) L^* = f(X^*)

where
L^*
is a vector of theoretical correct observations and
X^*
is a vector of correct values of parameters. For the given sample set
of observations L and the unknown vector of residuals v we
can express the estimate of parameters X as a nonlinear set of
equations

(12) L + v = f(X).

With approximate values X_0 of unknown parameters

(12) X = X_0 + x

we can linearize the equations (12)

L + v = f(X_0) + f'(X_0)x.

yielding the linear set of equations (1)

Unknown parameters in gama-local mathematical model are points
coordinates and orientation angles (transforming observed directions
to bearings). The observables described by functions (12) belong into
two classes

Internally in gama-local unknown corrections to linear
observables are computed in millimeters and corrections to angular
observables in centigrade seconds. To reflect the internal units in
used all partial derivatives of angular observables by coordinates are
scaled by factor
2000/pi.

When computing coefficients of project equations (1) we expect that
approximate coordinates of points are known with sufficient accuracy
needed for linearization of generally nonlinear relations between
observations and unknown paramters. Most often this is true but not
always and generally we have to check how close our approximation is to
adjusted parameters.

Generally we check linearization in adjustment by double calculation
of residuals

v^I = Ax - b,
v^II = ~l(~x) - l,

Program gama-local similarly computes and tests differences in
values of adjusted observations once computed from residuals
and once from adjusted coordinates. For measured directions
and angles gama-local computes in addition transverse deviation
corresponding to computed angle difference in the distance
of target point (or the farther of two targets for angle).
As a criterion of bad linearization is supposed positional
deviation greater or equal to 0.0005 millimetres.

From the practical point of view it might seem that the tolerance
0.0005 mm for detecting poor linearization is too strict. Its
exceeding in program gama-local results in repeated adjustment
with substitute adjusted coordinates for approximate. Given tolerance
was chosen so strict to guarantee that listed output results would
never be influenced by linearization and could serve for verification
and testing of numerical solutions produced by other programs.

Iterated adjustement with successive improvement of approximate
coordinates converges usually even for gross errors in initial estimates
of unknown coordinates. If the influence of linearization is detected
after adjustment, quite often only one iteration is sufficient for
recovering.

For any automatically controlled iteration we have to set up certain
stopping criterion independent on the convergence and results obtained.
Program gama-local computes iterated adjustment three times at maximum.
If the bad linearization is detected even after three readjustments it
signals that given network configuration is somehow suspicious.

5. Data structures and algorithms

5.1 Observation data and points

The Gama observation data structures are designed
to enable adjustment of any combination of possibly correlated
observations.
At its very early stage Gama was limited to adjustment of uncorrelated
observations. Only directions and distances were available and
observable’s weight was stored together with the observed value in a
single object. A single array of pointers to observation objects was
sufficient for handling all observations. So called orientation
shifts corresponding to directions measured form a point were stored
together with coordinations in point objects.

To enable adjustment of possibly correlated observations (like angles
derived from observed directions or already adjusted coordinates from
a previous adjustment) Gama has come with the concept of
clusters. Cluster is an object with a common
variance-covariance matrix and a list of pointers to observation
objects (distances, directions, angles, etc.). Weights were removed
from observation objects and replaced with a pointer to the cluster to
which the observation belong. All clusters are joined in a common
object ObservationData; similarly to observations, each cluster
contains a pointer to its parent Observation Data object.
Orientation shifts were separated from coordinates and are
stored in the cluster containing the bunch of directions and thus
number of orientations is not limited to one for a point.

This organisation of observational information has proved to be
effective. Template classes ObservationData and Cluster
are used as base classes both in gama-local and gama-g3

The following template class PointBase for handling point
information is used in gama-g3. The template class
PointBase relies internally on std::map container but
comes with its own interface (in gama-localstd::map
was used directly for storing points).

Glossary of the Mapping Sciences, Prepared by a Joint Committe of the
American Society of Civil Engineers, American Congress on Surveying
and Mapping and American Society for Photogrammetry and Remote Sensing
(1994), USA, ISBN 1-57083-011-8, ISBN 0-7844-0050-4

where
N = a/sqrt(1 - e^2 sin^2 B)
is the radius of curvature in the prime vertical, e^2 = (a^2 -
b^2)/a^2 is the first eccentricity for the given rotational
ellipsoid (spheroid) with semi-major axis a and semi-minor
axis b.

In the case of coordiante transformation from (X, Y, Z)
to (B, L, H), the longitude is given by the formula

tan L = Y / X.

Now we can introduce

D = sqrt(X^2 + Y^2),

so that the cartesian system become (D, Z).
Coordinates B and H are then usually computed by
iteration with some starting value of B_0, for example

tan B_0 = Z/D/(1 - e^2),

tan B = Z/D + N/(N+H) e^2 tan B, H = D / cos B = Z / sin B - N(1-e^2)

B. R. Bowring described a closed formula(2) that is more effective and sufficiantly
accurate and that is used in GNU Gama.

The centre of curvature C of the spheroid corresponding to
P’ is the point

(e^2 a cos^3 u, -e’^2 b sin^3 u)),

where e’^2 = (a^2 - b^2)/b^2 is second eccentricity and
u is the parametric latitude of the point
P’, (1-e^2)N sin B = b sin u.
Therefore

tan B = (Z + e’^2 b sin^3 u) / (D - e^2 a cos^3 u).

This is clearly an iterative solution; but it has been found that this
formula is extremely accurate using the single first approximation for
u for the
tan u = (Z/D)(a/b).
Maximum error in earth bound region is 3e-8 of
sexadecimal arc seconds (5e-7 millimetres); maximum is 0.0018” (0.1
millimetres) at height H = 2a.

The purpose of this License is to make a manual, textbook, or other
written document free in the sense of freedom: to assure everyone
the effective freedom to copy and redistribute it, with or without
modifying it, either commercially or noncommercially. Secondarily,
this License preserves for the author and publisher a way to get
credit for their work, while not being considered responsible for
modifications made by others.

This License is a kind of “copyleft”, which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.

We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.

APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be distributed
under the terms of this License. The “Document”, below, refers to any
such manual or work. Any member of the public is a licensee, and is
addressed as “you”.

A “Modified Version” of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.

A “Secondary Section” is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document’s overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject. (For example, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.

The “Invariant Sections” are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.

The “Cover Texts” are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.

A “Transparent” copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup has been designed to thwart or discourage
subsequent modification by readers is not Transparent. A copy that is
not “Transparent” is called “Opaque”.

Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format,
SGML or XML using a publicly available
DTD, and standard-conforming simple HTML designed
for human modification. Opaque formats include PostScript,
PDF, proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which
the DTD and/or processing tools are not generally available,
and the machine-generated HTML produced by some word
processors for output purposes only.

The “Title Page” means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, “Title Page” means
the text near the most prominent appearance of the work’s title,
preceding the beginning of the body of the text.

VERBATIM COPYING

You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and
you may publicly display copies.

COPYING IN QUANTITY

If you publish printed copies of the Document numbering more than 100,
and the Document’s license notice requires Cover Texts, you must enclose
the copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.

If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a publicly-accessible computer-network location containing a complete
Transparent copy of the Document, free of added material, which the
general network-using public has access to download anonymously at no
charge using public-standard network protocols. If you use the latter
option, you must take reasonably prudent steps, when you begin
distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location
until at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that edition to
the public.

It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.

MODIFICATIONS

You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:

Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.

List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has less than five).

State on the Title page the name of the publisher of the
Modified Version, as the publisher.

Preserve all the copyright notices of the Document.

Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.

Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.

Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document’s license notice.

Include an unaltered copy of this License.

Preserve the section entitled “History”, and its title, and add to
it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section entitled “History” in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.

Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the “History” section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.

In any section entitled “Acknowledgments” or “Dedications”,
preserve the section’s title, and preserve in the section all the
substance and tone of each of the contributor acknowledgments
and/or dedications given therein.

Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.

Delete any section entitled “Endorsements”. Such a section
may not be included in the Modified Version.

Do not retitle any existing section as “Endorsements”
or to conflict in title with any Invariant Section.

If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version’s license notice.
These titles must be distinct from any other section titles.

You may add a section entitled “Endorsements”, provided it contains
nothing but endorsements of your Modified Version by various
parties—for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.

You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.

COMBINING DOCUMENTS

You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice.

The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled “History”
in the various original documents, forming one section entitled
“History”; likewise combine any sections entitled “Acknowledgments”,
and any sections entitled “Dedications”. You must delete all sections
entitled “Endorsements.”

COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.

AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version
of the Document, provided no compilation copyright is claimed for the
compilation. Such a compilation is called an “aggregate”, and this
License does not apply to the other self-contained works thus compiled
with the Document, on account of their being thus compiled, if they
are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one quarter
of the entire aggregate, the Document’s Cover Texts may be placed on
covers that surround only the Document within the aggregate.
Otherwise they must appear on covers around the whole aggregate.

TRANSLATION

Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License provided that you also include the
original English version of this License. In case of a disagreement
between the translation and the original English version of this
License, the original English version will prevail.

TERMINATION

You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License. Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.

FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License “or any later version” applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.

A.1.1 ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:

Copyright (C) yearyour name.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being list their titles, with the
Front-Cover Texts being list, and with the Back-Cover Texts being list.
A copy of the license is included in the section entitled ``GNU
Free Documentation License''.

If you have no Invariant Sections, write “with no Invariant Sections”
instead of saying which ones are invariant. If you have no
Front-Cover Texts, write “no Front-Cover Texts” instead of
“Front-Cover Texts being list”; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.