[ < ] [ > ] [ << ] [ 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

  

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

  

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:

  

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:

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

• axes-xy="ne" orientation of axes x and y; value ne implies that axis x is oriented north and axis y is oriented east. Acceptable values are ne, sw, es, wn for left-handed coordinate systems and en, nw, se, ws for right-handed coordinate systems (default value is ne).
• angles="right-handed" defines counterclockwise observed angles and/or directions, value left-handed defines clockwise observed angles and/or directions (default value is left-handed).

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.

## Example

  ... ... 

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.

## Example

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

• sigma-apr = "10" value of a priori reference standard deviation—square root of reference variance (default value 10)
• conf-pr = "0.95" confidence probability used in statistical tests (dafault value 0.95)
• tol-abs = "1000" tolerance for identification of gross absolute terms in project equations (default value 1000 mm)
• sigma-act = "aposteriori" actual type of reference standard deviation use in statistical tests (aposteriori | apriori); default value is aposteriori
• 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.
• algorithm = "gso" numerical algortihm used in the adjistment (gso, svd, cholesky, envelope).
• languade = "en" the language to be used in adjustment output.
• encoding = "utf-8" adjustment output encoding.
• angles = "400" output results angular units (400/360).
• latitude = "50"
• ellipsoid
• 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.

## Example

  

 [ < ] [ > ] [ << ] [ 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.

• direction-stdev = "…" defines the implicit value of observed direction (default value is not defined)
• angle-stdev = "…" defines the implicit value of observed angle (default value is not defined)
• zenith-angle-stdev = "…" defines the implicit value of observed zenith angle (default value is not defined)
• azimuth-stdev = "…" defines the implicit value of observed azimuth angle (default value is not defined)
• distance-stdev = "…" defines the implicit value of observed horizontal distance (default value is not defined)

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.

## Example

  

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

## 2.7 Points

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

• id = "…" is the point identification attribute (mandatory); point identification is not limited to numbers; all printable characters can be used in identification.
• x = "…" specifies coordinate x
• y = "…" specifies coordinate y
• z = "…" specifies coordinate z, point height
• fix = "…" specifies coordinates that are fixed in adjustment; acceptable values are xy, XY, z, Z, xyz, XYZ, xyZ and XYz.
• adj = "…" specifies coordinates to be adjusted (unknown parameters in adjustment); acceptable values are xy, XY, z, Z, xyz, XYZ, xyZ and XYz.

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

  

 [ < ] [ > ] [ << ] [ 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

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

 [ 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

  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 1.6 

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

## Example

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

• to = "…" target point identification
• val = "…" observed direction; see section Angular units
• stdev = "…" standard deviation (optional)
• from_dh = "…" instrument height (optional)
• to_dh = "…" reflector/target height (optional)

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

## Example

  

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

## 2.10 Horizontal distances

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

• from = "…" standpoint identification
• to = "…" target identification
• val = "…" observed horizontal distance
• stdev = "…" standard deviation of observed horizontal distance (optional)
• from_dh = "…" instrument height (optional)
• to_dh = "…" reflector/target height (optional)

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

  

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

## 2.11 Angles

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

• from = "…" standpoint identification (optional)
• bs = "…" backsight target identification
• fs = "…" foresight target identification
• val = "…" observed angle; see section Angular units
• stdev = "…"  standard deviation (optional)
• from_dh = "…" instrument height (optional)
• bs_dh = "…" backsight reflector/target height (optional)
• fs_dh = "…" foresight reflector/target height (optional)

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

## Example

  

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

## 2.12 Slope distances

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

• from = "…" standpoint identification (optional)
• to = "…" target identification
• val = "…" observed slope distance
• stdev = "…" standard deviation of observed slope distance (optional)
• from_dh = "…" instrument height (optional)
• to_dh = "…" reflector/target height (optional)

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

## Example

  

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

## 2.13 Zenith angles

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

• from = "…" standpoint identification (optional)
• to = "…" target identification
• val = "…" observed zenith angle; see section Angular units
• stdev = "…" standard deviation of observed zenith angle (optional)
• from_dh = "…" instrument height (optional)
• to_dh = "…" reflector/target height (optional)

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

## Example

  

 [ < ] [ > ] [ << ] [ 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 />

• from = "…" standpoint identification
• to = "…" target point identification
• val = "…" observed azimuth; see section Angular units
• stdev = "…" standard deviation (optional)
• from_dh = "…" instrument height (optional)
• to_dh = "…" reflector/target height (optional)

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

  

 [ < ] [ > ] [ << ] [ 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:

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

## Example

  

 [ < ] [ > ] [ << ] [ 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.

## Example

  ... 

 [ < ] [ > ] [ << ] [ 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

• from_dh = "…" instrument height
• to_dh = "…" target height

## Example

  ... .. 

 [ < ] [ > ] [ << ] [ 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 input stream of points and observation data for the program GNU gama 

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

This document was generated by Ales Cepek on March 25, 2014 using texi2html 1.82.