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

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.

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

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.

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

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:

<?xml version="1.0" ?>
<gama-local xmlns="http://www.gnu.org/software/gama/gama-local">

GNU Gama uses non-validating parser and the XML Schema Definition namespace is not used in gama-local but it is essential for usage in third party software that might need XML validation.

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

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:

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.


   <description> ... </description>
   <parameters ... />
   <points-observations> ... </points-observations>

It is planned in future versions of the program to allow more <network> tags (analysis of deformations etc.) and definitions of new tags.

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

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.


A short description of a geodetic network ...

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

2.5 Network parameters

The network parameters may be listed with the following optional attributes of an empty-element tag <parameters />

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.


<parameters sigma-apr = "15"
            conf-pr   = '0.90'
            sigma-act = "apriori"
            update-constrained-coordinates = "no" />

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

2.6 Points and observations

The points and observations section is bounded by the pair tag <points-observations> and contains information about points, observed horizontal directions, angles, and horizontal distances, height differences, slope distances, zenith angles, observed vectors and control coordinates.

Optional attributes of the start tag <points-observations> allow for the definition of default values of standard deviations corresponding to observed directions, angles, and distances.

Implicit values of standard deviations for the observed distances are calculated from the model with three constants a, b, and c according to the formula

a + bD^c,

where a is a constant part of the model and D is the observed distance in kilometres. If the constants b and/or c are not given, default values b=0 and c=1 will be used.


<points-observations direction-stdev = "10"
                     distance-stdev  = "5 3 1" >
   <!-- ... points and observation data ... -->

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

2.7 Points

Points are described by the empty-element tags <point/> with the following attributes:

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.


<point id="1" y="644498.590" x="1054980.484" fix="xy"  />
<point id="2" y="643654.101" x="1054933.801" adj="XY" />
<point id="403" adj="xy" />

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

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

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)

[ 1.1  0.1  0.2   0    0    0
  0.1  1.2  0.3  0.4   0    0
  0.2  0.3  1.3  0.5  0.6   0
   0   0.4  0.5  1.4  0.7  0.8
   0    0   0.6  0.7  1.5  0.9
   0    0    0   0.8  0.9  1.6 ]

is coded in XML as

<cov-mat dim="6" band="2">
   1.1  0.1  0.2
        1.2  0.3  0.4
             1.3  0.5  0.6
                  1.4  0.7  0.8
                       1.5  0.9

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.


<obs from="418">
   <direction  to=  "2" val="0.0000"   stdev="10.0" />
   <direction  to="416" val="63.9347"  stdev="10.0" />
   <direction  to="420" val="336.3190" stdev="10.0" />
   <distance   to="420" val="246.594"  stdev="5.0"  />

<obs from="418">
   <direction  to=  "2" val="0.0000"   />
   <direction  to="416" val="63.9347"  />
   <direction  to="420" val="336.3190" />
   <distance   to="420" val="246.594"  />

   <cov-mat dim="4" band="0">
      100.00 100.00 100.00 25.00

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

2.9 Directions

Directions are expressed with the following attributes in an empty-element tag <direction />

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


<direction  to=  "2" val="0.0000"  stdev="10.0" />
<direction  to="416" val="63.9347" />

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

2.10 Horizontal distances

Distances are written using an empty-element tag <distance /> with attributes

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.


<distance from = "2"  to = "1" val = "659.184" />
<distance to ="422" val="228.207"  stdev="5.0"  />
<distance to ="408" val="568.341" />

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

2.11 Angles

Observed angles are expressed with the following attributes of an empty-element tag <angle />

Similar to distance observations, one observation set may group angles observed from several standpoints.


<angle from="433" bs="422" fs="402" val="128.6548" stdev="14.1"/>
<angle from="433" bs="422" fs="402" val="128.6548" />
<angle bs="422" fs="402" val="128.6548" stdev="14.1"/>
<angle bs="422" fs="402" val="128.6548"/>

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

2.12 Slope distances

Slope distances (space distances) are written using an empty-element tag <s-distance /> with attributes

Similar to horizontal distances, one observation set may group slope distances observed from several standpoints.


<s-distance from = "2"  to = "1" val = "658.824" />
<s-distance to ="422" val="648.618"  stdev="5.0"  />
<s-distance to ="408" val="482.578" />

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

2.13 Zenith angles

Zenith angles are written using an empty-element tag <z-angle /> with the following attributes

Similar to horizontal distances, one observation set may group zenith angles observed from several standpoints.


<z-angle from = "2"  to = "1" val = "79.6548" />
<z-angle to ="422" val="85.4890"  stdev="5.0"  />
<z-angle to ="408" val="95.7319" />

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

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.


<points-observations azimuth-stdev="15.0">

<azimuth from="1"  to=  "2" val= "96.484371" />

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

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:

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.


  <dh from="A" to="B" val=" 25.42" dist="18.1" />
  <dh from="B" to="C" val=" 10.34" dist=" 9.4" />
  <dh from="C" to="A" val="-35.20" dist="14.2" />
  <dh from="B" to="D" val="-15.54" dist="17.6" />
  <dh from="D" to="E" val=" 21.32" dist="13.5" />
  <dh from="E" to="C" val="  4.82" dist=" 9.9" />
  <dh from="E" to="A" val="-31.02" dist="13.8" />
  <dh from="C" to="D" val="-26.11" dist="14.0" />

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

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.


   <point id="1" x="100.00" y="100.00" />
   <point id="2" z="200.00" y="200.00" x="200.00" />
   <point id="3" z="300.00" />
   <cov-mat dim="6" band="5" >
       ...  <!-- covariances for 1x 1y 2x 2y 2z 3z -->

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

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.

Optional attributes of empty element tag <vec> for describing instrument and/or target height are


   <vec from="id1" to="id2" dx="..." dy="..." dz="..." />
   <vec from="id2" to="id3" dx="..." dy="..." dz="..." />
   <cov-mat dim="..." band="..." >

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

2.18 Example of local geodetic network

The XML input data format should be now reasonably clear from the following sample geodetic network. This example is taken from user’s guide to Geodet/PC by Frantisek Charamza.

<?xml version="1.0" ?>

<gama-local xmlns="http://www.gnu.org/software/gama/gama-local">
<network axes-xy="sw">

XML input stream of points and observation data for the program GNU gama

<!-- parameters are expressed with empty-element tag -->

<parameters sigma-act = "aposteriori" />


<!-- fixed point, constrained point -->

<point id="1" y="644498.590" x="1054980.484" fix="xy" />
<point id="2" y="643654.101" x="1054933.801" adj="XY" />

<!-- computed / adjusted points -->

<point id="403" adj="xy" />
<point id="407" adj="xy" />
<point id="409" adj="xy" />
<point id="411" adj="xy" />
<point id="413" adj="xy" />
<point id="416" adj="xy" />
<point id="418" adj="xy" />
<point id="420" adj="xy" />
<point id="422" adj="xy" />
<point id="424" adj="xy" />

<obs from="1">
     <direction  to=  "2" val=  "0.0000" stdev="10.0" />
     <direction  to="422" val= "28.2057" stdev="10.0" />
     <direction  to="424" val= "60.4906" stdev="10.0" />
     <direction  to="403" val="324.3662" stdev="10.0" />
     <direction  to="407" val="382.8182" stdev="10.0" />
     <distance   to=  "2" val= "845.777" stdev="5.0"  />
     <distance   to="422" val= "493.793" stdev="5.0"  />
     <distance   to="424" val= "288.301" stdev="5.0"  />
     <distance   to="403" val= "388.536" stdev="5.0"  />
     <distance   to="407" val= "498.750" stdev="5.0"  />

<obs from="2">
     <direction  to=  "1" val="0.0000"   stdev="10.0" />
     <direction  to="407" val="22.2376"  stdev="10.0" />
     <direction  to="409" val="73.8984"  stdev="10.0" />
     <direction  to="411" val="134.2090" stdev="10.0" />
     <direction  to="416" val="203.0706" stdev="10.0" />
     <direction  to="418" val="287.2951" stdev="10.0" />
     <direction  to="420" val="345.6928" stdev="10.0" />
     <direction  to="422" val="368.9908" stdev="10.0" />
     <distance   to="407" val="388.562"  stdev="5.0"  />
     <distance   to="409" val="257.498"  stdev="5.0"  />
     <distance   to="411" val="360.282"  stdev="5.0"  />
     <distance   to="416" val="338.919"  stdev="5.0"  />
     <distance   to="418" val="292.094"  stdev="5.0"  />
     <distance   to="420" val="261.408"  stdev="5.0"  />
     <distance   to="422" val="452.249"  stdev="5.0"  />

<obs from="403">
     <direction  to=  "1" val="0.0000"   stdev="10.0" />
     <direction  to="407" val="313.5542" stdev="10.0" />
     <distance   to="407" val="405.403"  stdev="5.0"  />

<obs from="407">
     <direction  to=  "1" val="0.0000"   stdev="10.0" />
     <direction  to="403" val="55.1013"  stdev="10.0" />
     <direction  to="409" val="193.3410" stdev="10.0" />
     <direction  to=  "2" val="239.4204" stdev="10.0" />
     <direction  to="422" val="323.5443" stdev="10.0" />
     <distance   to="409" val="281.997"  stdev="5.0"  />
     <distance   to="422" val="346.415"  stdev="5.0"  />

<obs from="409">
     <direction  to=  "2" val="0.0000"   stdev="10.0" />
     <direction  to="407" val="102.2575" stdev="10.0" />
     <direction  to="411" val="310.1751" stdev="10.0" />
     <distance   to="411" val="296.281"  stdev="5.0" />

<obs from="411">
     <direction  to=  "2" val="0.0000"   stdev="10.0" />
     <direction  to="409" val="49.8647"  stdev="10.0" />
     <direction  to="413" val="291.4953" stdev="10.0" />
     <direction  to="416" val="337.6667" stdev="10.0" />
     <distance   to="413" val="252.266"  stdev="5.0"  />
     <distance   to="416" val="360.449"  stdev="5.0"  />

<obs from="413">
     <direction  to="411" val="0.0000"   stdev="10.0" />
     <direction  to="416" val="295.3582" stdev="10.0" />
     <distance   to="416" val="239.745"  stdev="5.0"  />

<obs from="416">
     <direction  to=  "2" val="0.0000"   stdev="10.0" />
     <direction  to="411" val="68.8065"  stdev="10.0" />
     <direction  to="413" val="117.9922" stdev="10.0" />
     <direction  to="418" val="348.1606" stdev="10.0" />
     <distance   to="418" val="389.397"  stdev="5.0"  />

<obs from="418">
     <direction  to=  "2" val="0.0000"   stdev="10.0" />
     <direction  to="416" val="63.9347"  stdev="10.0" />
     <direction  to="420" val="336.3190" stdev="10.0" />
     <distance   to="420" val="246.594"  stdev="5.0"  />

<obs from="420">
     <direction  to=  "2" val="0.0000"   stdev="10.0" />
     <direction  to="418" val="77.9221"  stdev="10.0" />
     <direction  to="422" val="250.1804" stdev="10.0" />
     <distance   to="422" val="228.207"  stdev="5.0"  />

<obs from="422">
     <direction  to=  "2" val="0.0000"   stdev="10.0" />
     <direction  to="420" val="26.8834"  stdev="10.0" />
     <direction  to="424" val="225.7964" stdev="10.0" />
     <direction  to=  "1" val="259.2124" stdev="10.0" />
     <direction  to="407" val="337.3724" stdev="10.0" />
     <distance   to="424" val="279.405"  stdev="5.0"  />

<obs from="424">
     <direction  to=  "1" val="0.0000"   stdev="10.0" />
     <direction  to="422" val="134.2955" stdev="10.0" />



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

This document was generated by Ales Cepek on December 5, 2017 using texi2html 1.82.