Xml Startup Configuration¶

While configuration of Aguila is possible with the use of command line options and a configuration file, a more sophisticated scheme is possible by configuring Aguila with an XML start up file. The XML interface is unique in the following ways:

Specify draw properties per data item.
Specify real dates (e.g. 2005-02-10T18:15:00) and real time intervals (e.g. 24 hours).
Map data with different time dimensions to a single time line.

The XML interface is intended as an intermediate interface for other applications. For example, from a Python script it is relatively easy to generate the XML file. To use the XML interface a basic understanding of XML is required.

The XML Schema (Aguila.xsd) and samples of XML script files are distributed with a data set in the demos/xml distribution directory. References to .xml files in this chapter can be found in that directory. Note that the Aguila application does not require the file Aguila.xsd to be present. The correct version of Aguila.xsd is compiled into the Aguila application. For ease of reference, the schema is copied verbatim in section Aguila.xsd

Basic structure¶

In this section we only discuss the overall structure of the XML file. The detailed XML structure is documented in element specification within Aguila.xsd. Each Aguila XML file should have the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<aguila
   xmlns="http://www.pcraster.nl/pcrxml"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.pcraster.nl/pcrxml Aguila.xsd">
  <visualisationGroup>
   <!-- contents consisting of elements:
        - cursorValueMonitorFile  0 or 1
        - searchSpace             0 or 1
        - data                    0 or more
        - view                    0 or more
     -->
  </visualisationGroup>
</aguila>

The elements of the basic structure will be discussed in the reverse order of appearance.

view

A number of views can be specified. All view contents is specified by the dataset name as an item element. That same name may optionally appear as a data element. Example1.xml illustrates a number of points on the view specification:

The first appearance yields the position in the cursor and values matrix. Use a valueOnly element to obtain the preferred order (dem.map).
Time series file and cursor value graphs can be combined. See runoff and runoff.tss combined in a view in example1.xml.

data

A data element is used to tag a dataset name used in a view element with additional specifications: its draw properties and dataSpace. For example, in example1.xml the colour assignment of upstreamArea.map is set to shifted logarithmic.

searchSpace

With the searchSpace element one can describe the dimensions in which all data should be found if the data itself has no dataSpace sub element. In example1.xml the 28 model steps are set in the searchSpace and the timesteps are mapped to a real calendar date with a 6 hour time increment.

cursorValueMonitorFile

See the section called Program options.

fileToGetCursorValue

This element defines what file is read to set the applications cursor at each time Get is pressed in the Cursor Value Window. Currently only the x and y (space dimensions) are read. The file should be an XML file with the aguilaCursor element as root. See get.xml set in example1.xml.

Aguila.xsd¶

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Style Guide:
    See PCRaster.xsd
-->

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:pcr="http://www.pcraster.nl/pcrxml"
           elementFormDefault="qualified"
           targetNamespace="http://www.pcraster.nl/pcrxml">

<xs:include schemaLocation="commonTypes.xsd"/>

<!-- document (root) elements -->
<xs:element name="aguila"              type="pcr:Aguila">
 <xs:annotation>
   <xs:documentation>Aguila configuration/startup file</xs:documentation>
 </xs:annotation>
</xs:element>
<xs:element name="aguilaCursorValues"  type="pcr:AguilaCursorValues">
 <xs:annotation>
   <xs:documentation>contents of what is created when starting Aguila
                     with the cursorValueMonitorFile option
   </xs:documentation>
 </xs:annotation>
</xs:element>
<xs:element name="aguilaCursor"        type="pcr:Cursor">
 <xs:annotation>
   <xs:documentation>contents expected for fileToGetCursorValue,
                     connected to Get-button in Cursor Value Window
   </xs:documentation>
 </xs:annotation>
</xs:element>

<!--type definitions-->
<xs:complexType name="Aguila">
 <xs:annotation>
   <xs:documentation>Aguila configuration/startup file</xs:documentation>
 </xs:annotation>
 <xs:sequence>
  <xs:element name="multiView"     type="pcr:NrRowsNrCols"
                                  minOccurs="0" maxOccurs="1">
   <xs:annotation>
    <xs:documentation>Only used to translate a command line option.
    </xs:documentation>
   </xs:annotation>
  </xs:element>
  <xs:element name="visualisationGroup"     type="pcr:VisualisationGroup"
                                  minOccurs="1" maxOccurs="1"/>
 </xs:sequence>
</xs:complexType>

<xs:complexType name="VisualisationGroup">
 <xs:sequence>
  <xs:element name="cursorValueMonitorFile" type="xs:string"
                                   minOccurs="0" maxOccurs="1"/>
  <xs:element name="fileToGetCursorValue"   type="xs:string"
                                   minOccurs="0" maxOccurs="1"/>
  <xs:element name="searchSpace"   type="pcr:DataSpace"
                                   minOccurs="0" maxOccurs="1"/>
  <xs:element name="data"          type="pcr:AguilaData"
                                   minOccurs="0" maxOccurs="unbounded">
   <xs:annotation>
     <xs:documentation>Explictly defined data sources
     </xs:documentation>
   </xs:annotation>
  </xs:element>
  <xs:element name="view"   type="pcr:AguilaView"
                            minOccurs="0" maxOccurs="unbounded">
    <xs:annotation>
      <xs:documentation>
       Order of elements will define the order in the Cursor Value Dialog.
      </xs:documentation>
    </xs:annotation>
  </xs:element>
  <!--
  <xs:element name="initialCursor" type="pcr:Cursor"
                                   minOccurs="0" maxOccurs="1">
   <xs:annotation>
     <xs:documentation>Define initial cursor</xs:documentation>
   </xs:annotation>
  </xs:element>
  <xs:element name="namedCursors" type="pcr:NamedCursors"
                                   minOccurs="0" maxOccurs="unbounded"/>
   -->
 </xs:sequence>
</xs:complexType>

<xs:complexType name="DataSpace">
   <xs:annotation>
     <xs:documentation>
      Note that in practice only the scenarios element can
      occur more then once. All other maxOccurs value different
      from 1 are only for internal Aguila reasons (converting command
          line options to XML internally).
     </xs:documentation>
   </xs:annotation>
 <xs:sequence>
   <xs:element name="scenarios" type="pcr:StringSet"
                          minOccurs="0" maxOccurs="unbounded"/>
   <xs:element name="quantiles" type="pcr:FloatRangeOrSet"
                          minOccurs="0" maxOccurs="unbounded"/>
  <!-- Not yet
   <xs:element name="samples" type="pcr:OneBasedIntegerRange"
                          minOccurs="0" maxOccurs="unbounded"/>
    -->
   <xs:element name="timesteps" type="pcr:Timesteps"
                          minOccurs="0" maxOccurs="unbounded"/>
 </xs:sequence>
</xs:complexType>


<xs:complexType name="Timesteps">
 <xs:complexContent>
  <xs:extension base="pcr:OneBasedIntegerRangeOrSet">
   <xs:sequence>
    <xs:element name="dateMapper" type="pcr:DateMapper"
                          minOccurs="0" maxOccurs="1"/>
    <!-- TODO allow dal::StepMapper like here to,
              choice between dateMapper and stepMapper
     -->
   </xs:sequence>
  </xs:extension>
 </xs:complexContent>
</xs:complexType>

<xs:complexType name="DateMapper">
 <xs:sequence>
    <xs:element name="index" type="xs:unsignedInt">
     <xs:annotation>
       <xs:documentation>"epoch" of the index range
                         typically 1 or 0.
       </xs:documentation>
     </xs:annotation>
    </xs:element>
    <xs:element name="timeOfIndex" type="xs:dateTime">
     <xs:annotation>
       <xs:documentation>full calendar date of the index sibling element
                         Note that timezone information is not supported
       </xs:documentation>
     </xs:annotation>
    </xs:element>
    <xs:element name="duration" type="pcr:TimeDuration">
     <xs:annotation>
       <xs:documentation>duration of a timestep
       </xs:documentation>
     </xs:annotation>
    </xs:element>
 </xs:sequence>
</xs:complexType>


<xs:complexType name="AguilaView">
 <xs:choice maxOccurs="1" minOccurs="1">
   <xs:element name="map"       type="pcr:StringSet"/>
   <xs:element name="drape"     type="pcr:StringSet"/>
   <xs:element name="timeGraph" type="pcr:StringSet"/>
   <xs:element name="probabilityGraph" type="pcr:StringSet"/>
   <xs:element name="valueOnly" type="pcr:StringSet"/>
   <xs:element name="default"   type="pcr:StringSet"/>
   <xs:element name="test"      type="pcr:StringSet"/>
 </xs:choice>
</xs:complexType>

<xs:complexType name="AguilaData">
     <xs:annotation>
      <xs:documentation>
            TODO name is unique, addressing different datasets
            with same "name" but yielding different datasets by
            having a different DataSpace is done by setting another
            path.
       </xs:documentation>
      </xs:annotation>
 <xs:sequence>
   <xs:element name="name"           type="xs:string"/>
   <xs:element name="dataSpace"      type="pcr:DataSpace"
                          minOccurs="0" maxOccurs="1"/>
   <xs:element name="drawProperties" type="pcr:DrawProperties"
                          minOccurs="0" maxOccurs="1"/>
 </xs:sequence>
</xs:complexType>

<xs:complexType name="DrawProperties">
 <xs:sequence>
   <xs:element name="legendBorderValuesType" type="pcr:LegendBorderValuesType"
                          minOccurs="0" maxOccurs="1"/>
   <xs:element name="minimumCutOff" type="xs:double"
                          minOccurs="0" maxOccurs="1"/>
   <xs:element name="maximumCutOff" type="xs:double"
                          minOccurs="0" maxOccurs="1"/>
   <xs:element name="numberOfColours" type="pcr:Non0UnsignedInt"
                          minOccurs="0" maxOccurs="1"/>
   <xs:element name="colourAssignment" type="pcr:ColourAssignment"
                          minOccurs="0" maxOccurs="1"/>
   <xs:element name="drawMode" type="pcr:DrawMode"
                          minOccurs="0" maxOccurs="1"/>
   <xs:element name="palette" type="pcr:Palette"
                          minOccurs="0" maxOccurs="1"/>
  </xs:sequence>
</xs:complexType>

<xs:complexType name="Palette">
  <xs:sequence>
 <!-- choice
   <xs:element name="default" type="pcr:DefaultPaletteNames"/>
  -->
   <xs:element name="rgb" type="pcr:Rgb" minOccurs="1" maxOccurs="unbounded">
   <xs:annotation>
    <xs:documentation>
     * For nominal,ordinal,boolean data the element number (0-based) is mapped to the
       value. Values outside of [0,nr-of-rgb-elements> are mapped to element number:
       abs(value modulo nr-of-rgb-elements).
     * for scalar and directional data a colour ramp is created.
    </xs:documentation>
   </xs:annotation>
  </xs:element>
  </xs:sequence>
</xs:complexType>

<xs:complexType name="Rgb">
  <xs:sequence>
   <xs:element name="r" type="xs:unsignedByte" minOccurs="1" maxOccurs="1"/>
   <xs:element name="g" type="xs:unsignedByte" minOccurs="1" maxOccurs="1"/>
   <xs:element name="b" type="xs:unsignedByte" minOccurs="1" maxOccurs="1"/>
  </xs:sequence>
</xs:complexType>

<!-- TODO the knows palettes 
<xs:simpleType name="DefaultPaletteNames">
  <xs:restriction base="xs:string">
   <xs:enumeration value="netscape"/>
   <xs:enumeration value="greydirectional"/>
   <xs:enumeration value="etc"/>
  </xs:restriction>
</xs:simpleType>
-->

<xs:complexType name="LegendBorderValuesType">
 <xs:choice>
  <xs:element name="rounded" type="pcr:EmptyElement"/>
  <xs:element name="exact"   type="pcr:EmptyElement"/>
 </xs:choice>
</xs:complexType>

<xs:complexType name="ColourAssignment">
 <xs:choice>
  <xs:element name="linear"               type="pcr:EmptyElement"/>
  <xs:element name="trueLogarithmic"      type="pcr:EmptyElement"/>
  <xs:element name="shiftedLogarithmic"   type="pcr:EmptyElement"/>
  <xs:element name="confidenceLevel"      type="pcr:ConfidenceLevel"/>
 </xs:choice>
</xs:complexType>

<xs:complexType name="ConfidenceLevel">
 <xs:sequence>
  <xs:element name="value" type="xs:double">
   <xs:annotation>
    <xs:documentation>
        (1 - alpha)
        TODO: range [0,1]
   </xs:documentation>
  </xs:annotation>
  </xs:element>
 </xs:sequence>
</xs:complexType>

<xs:complexType name="DrawMode">
 <xs:choice>
  <xs:element name="fill"         type="pcr:EmptyElement"/>
  <xs:element name="contour"      type="pcr:EmptyElement"/>
 </xs:choice>
</xs:complexType>

<xs:complexType name="AguilaCursorValues">
 <xs:annotation>
   <xs:documentation>Contents Aguila cursor dump file</xs:documentation>
 </xs:annotation>
 <xs:sequence>
  <xs:element name="aguilaCursorValue"  type="pcr:AguilaCursorValue"
                          minOccurs="0" maxOccurs="unbounded"/>
 </xs:sequence>
</xs:complexType>

<xs:complexType name="AguilaCursorValue">
 <xs:annotation>
   <xs:documentation>Aguila current cursor dump</xs:documentation>
 </xs:annotation>
 <xs:sequence>
  <xs:element name="cursor"     type="pcr:Cursor"
                          minOccurs="0" maxOccurs="1"/>
  <xs:element name="dataValue"  type="pcr:DataValue"
                          minOccurs="0" maxOccurs="unbounded">
     <xs:annotation>
       <xs:documentation>y coordinate
       </xs:documentation>
     </xs:annotation>
  </xs:element>
 </xs:sequence>
</xs:complexType>

<xs:complexType name="Cursor">
 <xs:annotation>
   <xs:documentation>Current cursor position in the dimensions
   </xs:documentation>
 </xs:annotation>
 <xs:sequence>
  <xs:element name="time" type="xs:unsignedInt"
                          minOccurs="0" maxOccurs="1">
   <xs:annotation>
     <xs:documentation>integer timestep
     </xs:documentation>
   </xs:annotation>
  </xs:element>
  <xs:element name="date" type="xs:dateTime"
                          minOccurs="0" maxOccurs="1">
   <xs:annotation>
     <xs:documentation>real calendar date
                       Note that timezone information is not supported
     </xs:documentation>
   </xs:annotation>
  </xs:element>
  <xs:element name="x"    type="xs:double"
                          minOccurs="0" maxOccurs="1">
   <xs:annotation>
     <xs:documentation>x coordinate
     </xs:documentation>
   </xs:annotation>
  </xs:element>
  <xs:element name="y"    type="xs:double"
                          minOccurs="0" maxOccurs="1">
   <xs:annotation>
     <xs:documentation>y coordinate
     </xs:documentation>
   </xs:annotation>
  </xs:element>
 </xs:sequence>
</xs:complexType>

<xs:complexType name="DataValue">
 <xs:sequence>
  <xs:element name="name"  type="xs:string"/>
  <xs:element name="value" type="xs:string"/>
 </xs:sequence>
</xs:complexType>

</xs:schema>

Xml Startup Configuration¶

Basic structure¶

Aguila.xsd¶

Previous topic

Next topic

Table of Contents