diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 00000000..e69de29b diff --git a/404.html b/404.html new file mode 100644 index 00000000..e256f4b3 --- /dev/null +++ b/404.html @@ -0,0 +1,998 @@ + + + + + + + + + + + + + + + + + + + + + Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ +

404 - Not found

+ +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API/Python/index.html b/API/Python/index.html new file mode 100644 index 00000000..fd3e1eb7 --- /dev/null +++ b/API/Python/index.html @@ -0,0 +1,1134 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + Python - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Python

+ +

Call Underpass functions using Python C++ binding

+

Import Underpass package

+
    import underpass as u
+
+

Validate OSM Change

+
    with open("building.osc", 'r') as file:
+        data = file.read().rstrip()
+
+    validator = u.Validate()
+    result = validator.checkOsmChange(data, "building")
+
+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API/PythonDB/index.html b/API/PythonDB/index.html new file mode 100644 index 00000000..12b6e0cb --- /dev/null +++ b/API/PythonDB/index.html @@ -0,0 +1,1452 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + Python (DB) - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Python (DB)

+ +

Get data from the Underpass DB using Python

+

Connect to the database

+
from api.db import UnderpassDB`
+db = UnderpassDB("postgresql://localhost/underpass")
+db.connect()
+
+

Get raw data

+
from api import raw
+rawer = raw.Raw(db)
+
+

Get polygons

+
polygons = rawer.getPolygons( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "building=yes",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+
+

Get lines

+
lines = rawer.getLines( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "highway",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+
+

Get nodes

+
nodes = rawer.getNodes( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "amenity",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+
+

Get all together (polygons, lines and nodes)

+
nodes = rawer.getAll( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "building",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+
+

Get list of polygons

+
polygons = rawer.getPolygonsList( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "building",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+
+

Get list of lines

+
lines = rawer.getLinesList( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "building",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+
+

Get list of nodes

+
nodes = rawer.getNodesList( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "building",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+
+

Get list of all together (polygons, lines and nodes)

+
all = rawer.getAllList( 
+    area = "-180 90,180 90, 180 -90, -180 -90,-180 90",
+    tags = "building",
+    hashtag = "",
+    dateFrom = "",
+    dateTo = "",
+    page = 0
+)
+
+

Get data quality reports in CSV or GeoJSON

+
from api import report
+reporter = report.Report(db)
+
+

Get report for geometries

+
results = reporter.getDataQualityGeo(
+    fromDate = "2022-12-28T00:00:00", 
+    hashtags = ["hotosm"],
+    responseType = "csv"
+)
+
+

Get latest results for geometries

+
results = reporter.getDataQualityGeoLatest()
+
+

For getting results in CSV format, instead of GeoJSON

+
results = reporter.getDataQualityGeoLatest(
+    responseType = "csv"
+)
+
+

Get report for tags

+
results = reporter.getDataQualityTag(
+    fromDate = "2022-12-28T00:00:00", 
+    hashtags = ["hotosm"],
+    responseType = "csv"
+)
+
+

Get statistics for tags

+
results = reporter.getDataQualityTagStats(
+    fromDate = "2022-12-28T00:00:00", 
+    hashtags = ["hotosm"],
+    responseType = "csv"
+)
+
+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API/REST/index.html b/API/REST/index.html new file mode 100644 index 00000000..299639a8 --- /dev/null +++ b/API/REST/index.html @@ -0,0 +1,1458 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + REST - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

REST

+ +

Run a RESTful API

+

Setup & run

+

Install requirements

+
cd python/restapi/ && pip install -r requirements.txt
+
+

Setup DB connection

+

Set the database connection string as an environment variable:

+
export UNDERPASS_API_DB=postgresql://localhost/underpass
+
+

Run

+
uvicorn main:app --reload 
+
+

Making queries

+

Raw data

+

Get polygons

+
curl http://localhost:8000/raw/polygons -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "building=yes"}'
+
+

Get lines

+
curl http://localhost:8000/raw/lines -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "highway"}'
+
+

Get nodes

+
curl http://localhost:8000/raw/nodes -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "amenity"}'
+
+

Get all together (polygons, lines and nodes)

+
curl http://localhost:8000/raw/all -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "building"}'
+
+

Get list of polygons

+
curl http://localhost:8000/raw/polygonsList -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "building=yes"}'
+
+

Get list of lines

+
curl http://localhost:8000/raw/linesList -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "highway"}'
+
+

Get list of nodes

+
curl http://localhost:8000/raw/nodesList -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "amenity"}'
+
+

Get list of all together (polygons, lines and nodes)

+
curl http://localhost:8000/raw/allList -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"area":"-180 90,180 90, 180 -90, -180 -90,-180 90", "tags": "building"}'
+
+

Get data quality reports in CSV or GeoJSON

+

Get report for geometries

+
curl http://localhost:8000/report/dataQualityGeo -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"fromDate":"2022-12-28T00:00:00", "hashtags": "hotosm"}'
+
+

In CSV format instead of GeoJSON:

+
curl http://localhost:8000/report/dataQualityGeo/csv -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"fromDate":"2022-12-28T00:00:00", "hashtags": "hotosm"}'
+
+

Get report for tags

+
curl http://localhost:8000/report/dataQualityTags -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"fromDate":"2022-12-28T00:00:00", "hashtags": "hotosm"}'
+
+

Get statistics for tags

+
curl http://localhost:8000/report/dataQualityTagStats -X POST \
+    -H 'content-type: application/json' \
+    --data-raw '{"fromDate":"2022-12-28T00:00:00", "hashtags": "hotosm"}'
+
+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/bootstrapsh/index.html b/Dev/bootstrapsh/index.html new file mode 100644 index 00000000..ad21b582 --- /dev/null +++ b/Dev/bootstrapsh/index.html @@ -0,0 +1,1119 @@ + + + + + + + + + + + + + + + + + + + + + + + Using the bootstrap.sh script - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Using the bootstrap.sh script

+

This script is prepared for a quick bootstrap of the Underpass database.

+

Install requirements

+
    +
  • fiona (pip install fiona)
    • +
  • shapely (pip install shapely)
    • +
  • osm2pgsql (https://osm2pgsql.org/doc/install.html)
    • +
  • psql (https://www.postgresql.org/download/) +
    ## Quick start
+
+Run the script passing region, country and DB username as arguments, for example:
+
+```sh
+./bootstrap.sh -r south-america -c ecuador -l yes
+
    • +
+

This will:

+
    +
  1. Delete all entries into the database (WARNING: POTENTIAL LOSS OF DATA)
    2. +
  2. Download raw data from GeoFabrik
    3. +
  3. Run osm2psql for import it
    4. +
  4. Convert the country .poly file to .geojson and install config files
    5. +
  5. Run ./underpass --bootstrap for bootstrapping the validation table
    6. +
+

Script options

+
-r region (Region for bootstrapping)
+   africa, asia, australia, central-america
+   europe, north-america or south-america
+-c country (Country inside the region)
+-h host (Database host)
+-u user (Database user)
+-p port (Database port)
+-d database (Database name)
+-l yes (Use local files instead of download them)
+
+

Use the -l yes when you have your .pbf and .poly files already downloaded and +you don't want to download them again. The script will look for those files +using the -r and -c arguments, for example

+
./bootstrap.sh -r south-america -c ecuador -u underpass -l yes
+
+

Will look for these files:

+
ecuador-latests.osm.pbf
+ecuador.poly
+
+

OSM authentication for downloading data

+

If you want to bootstrap your database with ChangeSet data downloaded from + GeoFabrik, you'll need to be authenticated with an OSM account.

+

A good utility for doing this from command line is in the sendfile_osm_oauth_protector + repository.

+
git clone https://github.com/geofabrik/sendfile_osm_oauth_protector.git
+cd sendfile_osm_oauth_protector
+
+

Edit settings.json with your credentials:

+

```json + { + "user": "", + "password": "", + "osm_host": "https://www.openstreetmap.org", + "consumer_url": "https://osm-internal.download.geofabrik.de/get_cookie" +} +

And download your file:
+
+```sh
+curl https://osm-internal.download.geofabrik.de/africa/tanzania-latest-internal.osm.pbf \
+   --cookie "$(cat cookie_output_file.txt)" --output tanzania-latest.osm.pbf
+

+

Then you can move the pbf file to the underpass/utils directory and use the -l yes option.

+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/changefile/index.html b/Dev/changefile/index.html new file mode 100644 index 00000000..9c3ff166 --- /dev/null +++ b/Dev/changefile/index.html @@ -0,0 +1,1206 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + ChangeFile - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Replication Files

+

There are two types of data files related to changes in the map +data. These files contain all the changes made during a time interval, +every minute, hour, or daily data files are available from the +OpenStreetMap planet +server.

+

There are two different formats of change data, one for changesets, +and the other for the actual changes. Both are needed for filtering +changes to produce statistics.

+

Changeset

+

A changeset file contains only the data about the change, and not the +actual change itself. It contains the data of the change at the time +it's uploaded to OpenStreetMap. Each change has an action; create, +delete, modify. Each action then contains the changed objects in the +action. As this file contains the data created when uploading it to +OpenStreetMap, it's the only way to access the commit hashtags or +comments.

+

Hashtags didn’t exist until late 2014, so between 2014 and 2017, +hashtags were contained in the comment field. In 2017, the official +hashtag tag was added. The first mentions of the hashtags +#missingmaps and #hotosm starts 2017-10-20. A typical changefile +entry looks like this:

+
    <changeset id="12345" created_at="2014-10-10T01:57:09Z" closed_at="2014-10-10T01:57:23Z" open="false" user="foo" uid="54321" min_lat="-2.8042325" min_lon="29.5842812" max_lat="-2.7699398" max_lon="29.6012844" num_changes="569" comments_count="0">
+        <tag k="source" v="Bing"/>
+        <tag k="comment" v="#hotosm-task-001 #redcross #missingmaps"/>
+        <tag k="created_by" v="JOSM/1.5 (7182 en)"/>
+    </changeset>
+
+

The created_by and source fields can be used to generate +statistics of editor choices and imagery sources. Underpass uses only +the comment and hashtag fields currently as a way to group sets of +changes by organization, or mapping campaign.

+

OsmChange

+

And OsmChange file contains the data of the actual change. It uses the +same syntax as an OSM data file plus the addition of one of the three +actions. Nodes, ways, and relations can be created, deleted, or +modified. Multiple OSM object types can be in the same action. As this +data contains the actual change, it is used to filter by tag, or used +to do calculations, like the length of roads added.

+
    <modify>
+        <node id="12345" version="7" timestamp="2020-10-30T20:40:38Z" uid="111111" user="foo" changeset="93310152" lat="50.9176152" lon="-1.3751891"/>
+    </modify>
+    <delete>
+        <node id="23456" version="7" timestamp="2020-10-30T20:40:38Z" uid="22222" user="foo" changeset="93310152" lat="50.9176152" lon="-1.3751891"/>
+    </delete> 
+    <create> 
+        <node id="34567" version="1" timestamp="2020-10-30T20:15:24Z" uid="3333333" user="bar" changeset="93309184" lat="45.4303763" lon="10.9837526"/>\n 
+    </create> 
+
+

State Files

+

There are two types of state files, one for changesets and the other +for change files. The changeset one is the simplest, only containing +the last_run timestamp and a changeset sequence number. The first +state file starts 2016-09-07 10:45. An example changeset state file +is:

+
\---
+last_run: 2020-10-08 16:41:01.863533000 +00:00
+sequence: 4139643
+
+

The state file for change files contains more fields, but the only +ones needed for database updates are the timestamp of the data file, +and the sequence number. An example change file state file is:

+
#Thu Oct 08 16:38:04 UTC 2020
+sequenceNumber=4229951
+txnMaxQueried=3081409719
+txnActiveList=
+txnReadyList=
+txnMax=3081409719
+timestamp=2020-10-08T16\:38\:02Z
+
+

As the 3 digit prefix in the state filename matches the data file, +this is used to get the right data that matches that state. Since +the replication files are fetched via HTTP/HTTPS, there is no +timestamp available. To find a specific replication file, a state file +close to the timestamp is downloaded. Then the timestamp in the state +file is checked, and if it matches, the the 3 digit part of the state +file name can be used to find the appropriate replication data file.

+

Finding The Right Data File

+

It is desirable to be able to start processing changes starting with a +specific timestamp. This enables the end user to update databases +after a period of downtime. With minute updates, there are many +thousands of files. Since it takes about 10 milliseconds to download a +state.txt file from planet, scanning for files isn't really +practical. Once the proper data file is found, then it's easy to just +download the next data file in sequence.

+

Currently, the function PlanetReplicator::findRemotePath is the one +responsible for returning the file path from a timestamp. It's using +a list of of timestamps and sequence numbers stored in a local file +located in config/replicator/confiplanetreplicator.yaml for +calculating the path. This approach must be reviewed in order to +have better precision without the need of keeping that file up-to-date.

+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/chroots/index.html b/Dev/chroots/index.html new file mode 100644 index 00000000..9f00d25e --- /dev/null +++ b/Dev/chroots/index.html @@ -0,0 +1,1141 @@ + + + + + + + + + + + + + + + + + + + + + + + + + Chroots - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

[ THIS DOCUMENT NEEDS REVIEW ]

+

Building Packages in a Chroot

+

To distribute binary packages for a variety of platforms of varying +versions, it's common to use a chroot to build in. This is to make +sure that a the package binary is linked against the right libraries, +which is required so the user doesn't have to build anything from +source. Unlike Docker or Virtualbox, a chroot uses the base running +kernel on host machine, but provides a different set of runtime +libraries and tools.

+

Creating a Chroot

+

All platforms that use the .deb packaging format, like Debian and +Ubuntu, can use the debbootstrap program to create the +chroot. Debootstrap lets you pick the architect to support, +--arch amd64 builds files for the X86_64 platform. after that the +version of the distribution is specified, followed by the directory to +install the files in, and finally the URL to download packages +from. Once done, change to the installation directory, and type sudo +chroot .. You'll now be in a minimal runtime environment. The first +thing I do is create a /etc/debian_chroot file containing the name +of the distribution. This puts the this value into the command prompt +for the shell, which is very useful when you have multiple chroots.

+

As the chroot program requires one to be root, a utility program +called schroot can be used to fake root. Once the initial chroot is +created, change to the directory containing the downloaded files, and +type these shell commands. Some of the programs used to build packages +need these, which aren't present in the chroot, as they have to be +shared from the host platform.

+
mount -t proc proc /proc
+mount --rbind /sys sys/
+mount --rbind /dev dev/
+
+

Once that initial setup is done, it's time to download more +packages. The default config file for a chroot is limited to just the +main repository. Not all of the packages Underpass depends on are in +main, so add universe to get the rest, and then apt-get +update. Your /etc/apt/sources.list file should now look like this:

+
deb http://archive.ubuntu.com/ubuntu focal main universe
+
+

Finally edit ~/.bashrc and add these three lines at the bottom. One +specifies the path to a file pkg-config needs, but isn't always +distributed, so it's included. The other is for locale, so it stops +clutterin the terminal with warnings.

+
export PKG_CONFIG_PATH=/home/rob/underpass/m4
+export LANG=C
+export GPG_TTY="$(tty)"
+
+

To create signed packages, you need a GPG key pair setup, so might +as well do that now. Type gpg --full-generate-key, and answer the +questions. This will only work if you've execute the mount commands as +documented above.

+

For Debian

+
sudo /usr/sbin/debootstrap --arch amd64 bullseye bullseye/ http://deb.debian.org/debian/
+
+

Start by installing packages needed to build Underpass.

+
sudo apt-get -y install \
+    git gcc g++ pkg-config make debhelper debconf chrpath ccache devscripts gpg \
+    libgdal-dev libosmium2-dev libpq-dev libgumbo-dev \
+    libssl-dev libpq5-dev libxml++2.6-dev libboost-all-dev
+
+

Ubuntu Focal (20.04 LTS)

+
sudo /usr/sbin/debootstrap --arch amd64 focal focal/ http://archive.ubuntu.com/ubuntu/
+
+

Start by installing packages needed to build Underpass.

+
sudo apt-get -y install \
+    git make gcc g++ pkg-config gpg debhelper debconf devscripts python3-all \
+    libgdal-dev libpq-dev libgumbo-dev openmpi-bin \
+    libxml++2.6-dev ccache libssl-dev libzip-dev libbz2-dev \
+    libboost-all-dev libosmium2-dev osmium-tool \
+    doxygen librange-v3-dev libtool-bin libltdl-dev  
+
+

Ubuntu Groovy (20.10)

+
sudo /usr/sbin/debootstrap --arch amd64 groovy groovy/ http://archive.ubuntu.com/ubuntu/
+
+

Install dependencies as above. Note that the version of boost is 1.74

+

Ubuntu Hirsute (21.04)

+
sudo /usr/sbin/debootstrap --arch amd64 hirsute hirsute/ http://archive.ubuntu.com/ubuntu/
+
+

Install dependencies as above. Note that the version of boost is 1.74

+

Building Libpqxx Packages

+

The version of libpqxx (6.x) that's included in current (Aug 2021) +distribution like Debian Bullseye or Unbuntu Hirsute (21.04) has a bug triggered +by libxml++. Since Underpass uses libxml++ and libpqxx, we have to +build a package of a newer version (7.x). I added Debian packaging +files to a git repository to make this easier, Get that fork here:

+
git clone https://github.com/robsavoye/libpqxx.git
+
+

Once I do that, I run git tag, and the checkout the latest official +release branch. There's a configure bug in the libpqxx sources I +haven't gotten around to fixing yet, so I edit configure.ac, and +comment out this one line like so:

+
dnl AX_CXX_COMPILE_STDCXX_17([noext])
+
+

Then run ./autogen.sh, which produces the scripts used for +configuring. Now that you have the configure script, configure +libpqxx like this:

+
./configure CXX="ccache g++" CXXFLAGS="-std=c++17 -g -O2" --disable-dependency-tracking
+
+

After that, change to the debian directory, and type make deb -i +-k. That'll build the deb packages, and at the end, have you GPG sign +them. Once built, install the two packages, and you're all set to go +build Underpass.

+

Building Underpass Packages

+

The Underpass git repository is at:

+

https://github.com/hotosm/underpass.git

+

Once downloaded, change to the source directory and run +./autogen.sh. Once the configure files have been built, configure +Underpass like this:

+
./configure CXX="ccache g++" CXXFLAGS="-std=c++17 -g -O2" --disable-dependency-tracking
+
+

and then typing make deb -i -k builds the packages, and has you sign them.

+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/coding/index.html b/Dev/coding/index.html new file mode 100644 index 00000000..f0ba9ce9 --- /dev/null +++ b/Dev/coding/index.html @@ -0,0 +1,1198 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + Coding - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Underpass Coding Style

+

This documents the prefered coding style for Underpass. The goal +of this coding style is to make code consistent amongst developers, +and to write code that is focused on being readable and +compact. Because the existing code is written with this goal, using +reformatting tools like indent or clang-format is discouraged.

+

The easy way to follow this style is to use +cc-mode +in Emacs. Spaces will be used instead of TABS, since different systems +or users may have TAB set differently. Indents are 4 spaces, instead +of 8.

+

Documentation

+

All code will use Doxygen style +comments. Classes and methods should each have a comment so a short +description will be displayed in the output files Doxygen +generates. Each file should also have a brief description.

+

Line Length

+

For decades lines were limited to 80 charcters or less, which was +based on what a CRT could display. With modern monitors this +limitation doesn't exist. The Linux kernel has been using 132 character +line length, so this project does too.

+

Line breaks

+

Line breaks are used to break up long lines, with the remainder +indented to be clear it's a continuation of the line. Some times a +long line is prefered if adding a line break makes the code less +readable.

+

Brace Location

+

The opening brace for most code is on the same line as the line of +code. Putting an opening brace on a line by itself adds too much +unnecessary whitespace. A closing brace is usually on a line by +itself.

+

Some examples:

+
namespace replication {
+class StateFile;
+};
+
+class RawChangeset {
+  public:
+      void foo(void);
+};
+
+

In C++ a conditional with a single line following the test is legal, +but braces should be used to make it clearer.

+
if (i == 20) {
+   // do something
+}
+
+

Naming Convention

+

Underpass uses Camel Case, +which uses capitalization instead of underbars for class definitions, +function or C++ methods, and variable. For example RawChange instead +of raw_change. Class names capitalize the first letter as well, +where the methods in the class start with a lower case letter.

+

Names should be descriptive, and when possible, avoid abbrevations +unless they are commonly used.

+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/dataflow.png b/Dev/dataflow.png new file mode 100644 index 00000000..c47b7499 Binary files /dev/null and b/Dev/dataflow.png differ diff --git a/Dev/dataflow/index.html b/Dev/dataflow/index.html new file mode 100644 index 00000000..7808ed51 --- /dev/null +++ b/Dev/dataflow/index.html @@ -0,0 +1,1238 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + Data flow - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Underpass Data Flow

+

Flow Chart

+

The Overpass data storage contains information from several +sources. Underpass has to duplicate this collection of data and +aggregate it into a similar structure. The primary data is the map +data itself, which contains no history or change data.  All the +necessary data is available from planet.openstreetmap.org, but is not +all in the same format, and is in different places on the planet +server. There appear to be no open-source projects that aggregate all +this data together other than Overpass.

+

There are two different change file formats. One includes the hashtags +and comments from the change. The other is the changed data +itself. Both of these data files can be downloaded from the planet +server, and can also be updated with minutely changes. There is +currently no open source software that I can find to process the +changeset file, nor to merge it with the other change data. This is +one of the tasks Underpass needs to handle. To support the Missing +Maps leaderboard, and OSM Stats. the changes are used to calculate the +totals of highways, waterways, and buildings added or edited in that +change. A change it the data at uploading to OSM time. Underpass will +recreate the history as it processes the change files.

+

For producing statistics, the process initially starts by downloading +the large data file of all changes made since 2005. As hashtags didn’t +exist until late 2014, data prior to then is ignored. Starting in +2014, hashtags were stored in the comments field of the map data, till +the hashtag field was added in late 2017. This data file has some of +the fields we want, which is documented here.

+

Briefly, Underpass extracts the hashtag (if there are any) and +changeset timestamp. The next task is to download the changed data +itself. This is available at planet.openstreetmap.org as well. The +osmium program can do +this, but does not support importing it into a database. It only +works with disk files. The Replicator program will do +a similar task, namely download the changes, but will apply them to +the statistics database. While Replicator processes the changes, it +will also update the statistics database by adding the totals for the +new data to the existing amounts. For statistics collection, the +core OSM database isn't needed.

+

However the changes do need to be applied to the OSM map database, so +when processing exports, or later doing validation, it’s up to +date. The entire update process of both databases has to happen within +one minute if we want to update that frequently, which is the +goal. When updating the map database, any node or way that is changed +will be stored in the database in a new table. This will create the +history needed for augmented diffs. Only the previous version is +stored, any older entries will be deleted from the history database.

+

Source Data

+

Underpass collects data from multiple sources, primarily the +Change Files from the OpenStreetMap planet +server. Changes are availble with different time intervals. The +minutely one are the primary data source. There are two sets of +minute update, one documents the change and the other is the changed +data itself.

+

Directory Organization

+

Almost all directories and files are numerically based. The very top +level contains the +intervals, and the changeset directories, and looks like this:

+
minute/
+changeset/
+hour/
+day/
+
+

Under each one of these top level directories are the numerical +ones. At the lowest level there are 1000 files in each directory, so +the value is always a consistent 3 digit number.

+
...
+002/
+001/
+000/
+
+

Under each on of these sub-directories are the actual data ones

+
999/
+998/
+...
+001/
+000/
+
+

Each one of these directories contains 1000 files, roughly 16 hours +of data.

+
replication/002/
+replication/002/002/
+replication/002/002/002/
+replication/002/002/002/
+replication/002/002/002/002.state.txt
+replication/002/002/002/002.osm.gz
+
+

The state file contains the ending timestamp of the associated data +file. Underpass uses the state.txt file to find the right data. THe +timestamps are not a consistent time interval, so it's not really +possible to just calculate the right data file. To speed up searching +for the right data file based on a timestamp, Underpass downloads them +and enters the path to the data file and the timestamp into postgres.

+

This process works forward and backwards. When initializing a database +from scratch, Underpass will just bulk download the state files, +starting with the most recent ones, and then going backwards in +time. It takes about a week to download all the minutely state.txt +files, hourly only a few hours.

+

Underpass can also monitor for new data files, so as to keep up to +date. If the database is up to date, the threads are put to sleep, and +wake up a minute later to see if there are new files. If behind by +several minutes, Underpass will bulk download them until caught up.

+

Underpass uses simple threading, so can utilize multiple CPU +cores. When a new data file is downloaded, it's uncompressed and +parsed. During the parsing process, some data validation is done. +If a change fails validation, it's written to a database table so a +validator can look into the issue later. If it passes validation, then +statistics are calculated, and written to the database.

+

Output Databases

+

Underpass currently writes to 1 primary database: the +underpass database, which stores all the calculated statistics, data +validation results and raw OSM data that also gets updated every minute.

+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/debugging/index.html b/Dev/debugging/index.html new file mode 100644 index 00000000..738b9958 --- /dev/null +++ b/Dev/debugging/index.html @@ -0,0 +1,1200 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + Debugging - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Debugging

+ +

Development and debugging

+

Build flags

+

The following flags are suggested when running the configuration for building:

+

../configure CXX="ccache g++" CXXFLAGS="-std=c++17 -g -O0" CPPFLAGS="-DTIMING_DEBUG"

+

Debugging with GDB

+

apt-get install gdb

+

Setup an alias for gdb in your bash profile, +adding the following line add the bottom of ~/.bashrc:

+

alias lg='libtool --mode=execute gdb'

+

And you'll be able to run the debugger, for example:

+

lg src/testsuite/libunderpass.all/yaml-test +lg --args ./underpass --bootstrap

+

Debugging in MacOS

+

With GDB

+

It's also possible to debug Underpass on MacOS. You should use glibtool instead of libtool.

+

brew install gdb

+

Note that gdb requires special privileges to access Mach ports. +You will need to codesign the binary. For instructions, see: https://sourceware.org/gdb/wiki/PermissionsDarwin

+

Add the alias in your ~/.bashrc file:

+

alias lg='glibtool --mode=execute gdb'

+

With LLDB

+

lldb -- src/testsuite/libunderpass.all/yaml-test +lldb -- .libs/underpass --bootstrap

+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/engine/index.html b/Dev/engine/index.html new file mode 100644 index 00000000..70d80c5a --- /dev/null +++ b/Dev/engine/index.html @@ -0,0 +1,1098 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + Engine - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Underpass

+

Underpass is a C++ API and utility programs for manipulating +OpenStreetMap data at the database and raw data file level. It can +download replication files from the OSM planet server and use these +files to update a local copy of the OSM database, or analyze the +changes to generate statistics. It is designed to be high +performance on modest hardware.

+

Currently this is usually done using Overpass, which can be +self-hosted or accessed remotely. Overpass has major performance +issues though, namely it’s single threaded, and doesn’t use a real +database. What Overpass does is support a wide range of querying OSM +data, and can handle rather complicated filters. Much of that +functionality is not needed for supporting statistics collection and +simple validation.

+

Underpass is designed to function as a replacement for a subset of +Overpass’s functionality. It is focused on analyzing the change data +every minute, and generating statistics or doing validation of the +metadata. It is designed to be able to process large files +by streaming the data.

+

Rather than using disk based tempfiles, it has a self-hosted database +centric design for better performance. It uses Postgresql with the +Postgis extension, both commonly used for core OSM infrastructure. One +big advantage of using postgres is it supports utilizing multi-core +processors for faster SQL queries. It can optionally use GPU +support for faster geospatial +queries.

+

The other primary design goal of Underpass is to be maintainable for +the long term. It uses common open source infrastructure to make it +accessible to community developers. The primary dependencies, which +are used by multiple other core OSM projects are these:

+
    +
  • Uses the GNU autotools for multi-platform support
    • +
  • Uses SWIG for bindings to multiple languages
    • +
  • Uses Boost for additional C++ libraries
    • +
  • Uses GDAL for reading Geospatial files
    • +
  • Uses PQXX for accessing Postgres
    • +
  • Uses Libxml++ for parsing XML files
    • +
  • Uses Doxygen for producing code documentation
    • +
+

Ideally Underpass can be used by other projects needing to do similar +tasks without Overpass. It should be able to support collecting more +statistics than are currently used. Since much of Underpass deals with +the low level data flow of OpenStreetMap, long-term it can be used to +support future projects as a common infrastructure for database +oriented mapping tasks.

+

A critical future project is conflation and validation of existing +data and mapathons. Underpass will support the database management +tasks those projects will need. The same database can also be used for +data exports, and Underpass can be used to keep that data up to +date. What the Overpass data store contains is history information, +change information, and the actual OSM data. Underpass can access this +same information by processing the change data itself.

+

Dependencies

+

Underpass requires a modern C++ compiler that supports the 2011 C++ +standard. The 2011 standard simplified the syntax by adding the auto +keyword, and thread support became part of the standard C++ +library. Underpass is a heavy user of of the boost libraries, and +also requires reasonably up to date C++ libraries for other +dependencies. Underpass also uses the ranges-v3 library. This will be +in the 2020 C++ standard, but hasn't been released yet.

+

Fedora 33, Debian Buster, and Ubuntu Groovy contain a package for +librange-v3, which is the code base for what will be in +C++ 2020. Both Debian Buster and Ubuntu Groovy ship libpqxx 6.x, +which has a bug which has been fixed in libpqxx 7.x. Fedora 33 ships +the newer version.

+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/install-with-docker/index.html b/Dev/install-with-docker/index.html new file mode 100644 index 00000000..de77e077 --- /dev/null +++ b/Dev/install-with-docker/index.html @@ -0,0 +1,1125 @@ + + + + + + + + + + + + + + + + + + + + + + + Install with docker - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Install with docker

+ +

Docker installation

+

This is the easiest way to get Underpass up and running:

+
docker-compose up -d
+
+

Setup and run demo

+

Bootstrap the database for a country

+

Requirements:

+
    +
  • fiona (pip install fiona)
    • +
  • shapely (pip install shapely)
    • +
  • osm2pgsql (https://osm2pgsql.org/doc/install.html)
    • +
  • psql (https://www.postgresql.org/download/)
    • +
+

Run this utility script for bootstrap the database with data for a country:

+

cd utils && ./bootstrap.sh -r asia -c nepal
+
+Regions (-r) are:

+
    +
  • africa
    • +
  • asia
    • +
  • australia-oceania
    • +
  • central-america
    • +
  • europe
    • +
  • north-america
    • +
  • south-america
    • +
+

Countries (-c) is the name of the country inside the region.

+

Data is downloaded from GeoFabrik, if you are not sure of what name you need to use, please check there.

+

Configure the UI

+

You can find the UI's playground here: http://localhost:5000

+

Edit this file with the center coordinates for the map:

+

js/src/fixtures/center.js

+

And copy it to the container:

+
docker cp js/src/fixtures/center.js underpass_ui:/code/src/fixtures/center.js
+
+

Refresh the page and you'll see your map centered in the new coordinates, +displaying raw data and validation results on top of the OSM map.

+

Keep the database up-to-date minutely

+

Run this command for start processing data from 2 days ago:

+
docker exec -w /code/build underpass ./underpass -t $(date +%Y-%m-%dT%H:%M:%S -d "2 days ago")
+
+

On MacOS, the date command is different:

+
docker exec -w /code/build underpass ./underpass -t $(date -v -2d +%Y-%m-%dT%H:%M:%S)
+
+

For running underpass as a daemon, use the -d option:

+
docker exec -d -w /code/build underpass ./underpass -t $(date -v -2d +%Y-%m-%dT%H:%M:%S)
+
+

Stop and start underpass

+

If you want to stop the process, you can kill the container:

+
docker kill underpass
+
+

Then, you'll have to run docker-compose up -d before starting the process again.

+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/install/index.html b/Dev/install/index.html new file mode 100644 index 00000000..e83eca21 --- /dev/null +++ b/Dev/install/index.html @@ -0,0 +1,1069 @@ + + + + + + + + + + + + + + + + + + + + + + + Underpass installation - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Underpass installation

+

Tested in operating system Ubuntu 22.10

+

Install binary dependencies

+
sudo apt-get update \
+    && apt-get install -y software-properties-common \
+    && apt-get update && apt-get install -y \
+        libboost-dev \
+        autotools-dev \
+        swig \
+        pkg-config \
+        gcc \
+        build-essential \
+        ccache \
+        libboost-all-dev \
+        dejagnu \
+        libjemalloc-dev \
+        libxml++2.6-dev \
+        doxygen \
+        libgdal-dev \
+        libosmium2-dev \
+        libpqxx-dev \
+        postgresql \
+        libgumbo-dev \
+        librange-v3-dev
+
+

Build Underpass

+
$ ./autogen.sh && \
+  mkdir build && cd build && \ 
+  ../configure && make -j$(nproc) && sudo make install
+
+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/osmstats/index.html b/Dev/osmstats/index.html new file mode 100644 index 00000000..892d5e8f --- /dev/null +++ b/Dev/osmstats/index.html @@ -0,0 +1,1593 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + OSM Stats - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

OSM Stats

+

The Red Cross maintains statistics of changes, so it’s possible to +track the mapping progress of individual users, teams, and mapping +campaigns. Underpass writes directly to the postgres database used for +OSM Stats. Underpass has the ability to recreate this database and +populate it with data from the raw data files. Underpass uses +replication change files to update these tables. The +database schema contains a number of tables which are documented here:

+

 

+

OSM Stats Tables

+

The OSM schema contains a number of tables, which are designed to +support the web front end. the raw_ tables are mostly static, and +are simply a matching of an ID to a name for display. There are other +smaller tables for the same purpose, usedc to group queries together +for the front-end.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeywordDescription
Augmented_diff_statusContains the changeset ID of the augmented diff, and the timestamp of the last update
badgesContains the the badge ID, the category, the badge name, and the experience level
badges_usersContains the user ID, the badge category, the badge name, and the user experience level
changesets_statusContains the changeset ID and the timestamp for the update
raw_changesetsContains all the data of the changeset
raw_changesets_countriesContains the changeset ID and an index into the raw_changesets table
raw_changesets_hashtagsContains the changeset ID and the an index into the raw_hashtag table
raw_countriesContains an index number, and the country or state name plus a display abbreviation
raw_hashtagsContains an index number and hashtag used
raw_usersContains only the user ID and name
spatial_ref_sysGeospatial data used by Postgis
badge_updater_status
+

 

+

raw_changesets Table

+

The main table is raw_changesets, which contains extracted data from +the two files is then processed to create the various statistics. The +counters use the existing data, and only add to this value based on +what is in the change file, as this requires much less processing +time. This is the primary table Underpass updates the data in.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeywordDescription
idThis is the ID of the changeset, and comes from the changeset file
road_km_addedThis value is updated by counting the length of roads added or deleted by the user in the change file
road_km_modifiedThis value is updated by counting the length of existing roads modified by the user in the change file
waterway_km_addedThis value is updated by counting the length of waterways added or deleted by the user in the change file
waterway_km_modifiedThis value is updated by counting the length of existing waterways modified by the user in the change file
roads_addedThis value is updated by counting the roads added or deleted by the user in the change file
roads_modifiedThis value is updated by counting the existing roads modified by the user in the change file
waterways_addedThis value is updated by counting the roads added or deleted by the user in the change file
waterways_modifiedThis value is updated by counting the existing waterways modified by the user in the change file
buildings_addedThis value is updated by counting the buildings added by the user in the change file
buildings_modifiedThis value is updated by counting the existing buildings modified by the user in the change file
pois_addedThis value is updated by counting the POIs added by the user in the change file
pois_modifiedThis value is updated by counting the existing POIs modified by the user in the change file
editorThe editor used, and comes from the changeset
uidThe user ID, comes from the changeset
created_atThe timestamp this changeset was created, comes from the changeset
closed_atThe timestamp this changeset was closed, comes from the changeset
verifiedWhether this data has been validated
updated_atThe timestamp this change was applied to the database
augmented_diffs
+

 

+

raw_users Table

+ + + + + + + + + + + + + + + + + +
KeywordDescription
idOSM user ID
nameOSM username
+

 

+

raw_hashtags Table

+ + + + + + + + + + + + + + + + + +
KeywordDescription
idhashtag ID, internal use only
hashtagOSM username
+

 

+

raw_countries Table

+ + + + + + + + + + + + + + + + + + + + + +
KeywordDescription
idcountry ID, internal use only
nameCountry full name
codeThe 3 letter ISO abbreviation
+

 

+

raw_changesets_countries Table

+ + + + + + + + + + + + + + + + + +
KeywordDescription
changeset_idThe changeset ID
country_idThe country ID
+

 

+

raw_changesets_hashtags Table

+ + + + + + + + + + + + + + + + + +
KeywordDescription
changeset_idThe changeset ID
hashtag_idThe hashtag ID
+

 

+

changesets_status Table

+ + + + + + + + + + + + + + + + + +
KeywordDescription
idThe changeset ID
updated_atTimestamp of the update
+

 

+

badge Table

+ + + + + + + + + + + + + + + + + + + + + + + + + +
KeywordDescription
idThe badge ID
categoryThe badge catagory
nameThe badge name
levelThe badge level
+

 

+

badges_users Table

+ + + + + + + + + + + + + + + + + + + + + +
KeywordDescription
uidThe OSM user ID
badge_idThe badge ID
updated_atThe timestamp of the user receiving this badge
+

 

+

augmented_diff_status Table

+ + + + + + + + + + + + + + + + + +
KeywordDescription
idThe change ID
updated_atThe timestamp when this change was applied
+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/replication/index.html b/Dev/replication/index.html new file mode 100644 index 00000000..a6843d35 --- /dev/null +++ b/Dev/replication/index.html @@ -0,0 +1,1071 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + Replication - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Replication

+

Replication is the process of appyling a set changes to data. There +are two types of replication files available for OpenStreetMap data, +changesets and changefiles from their +planet server. The +level directory contains several subdirectories. All the +subdirectory structures are the same.

+

Each of the directories contains a 3 digit name. A new +directory is created whenever there are 1 million data files +created. Each of these top level's subdirectories contains 1000 +subdirectories, also named with a 3 digit value. Under those +subdirectories, there are 1000 entries. The time interval between map +updates is not consistent, so a state.txt file is used. This file +contains the timestamp of the accompanying data file. The data file is +compressed, and contains all the changed data.

+

For the change files, the directory structure looks like this:

+
minute/001/001/001/001.state.txt
+minute/001/001/001/001.osc.gz.
+minute/001/001/001/002.state.txt
+minute/001/001/001/002.osc.gz.
+etc...
+
+

Changesets are slightly different, as they contain no map data, just +data on the changes made when uploaded.

+
changesets/001/001/001.osm.gz
+changesets/001/001/001.state.txt
+etc...
+
+

Since the data file uses the same 3 digit prefix as the state file, +it's easy to get the right data for the timestamp. Because the size of +the data in the changefiles varies, plus CPU load, network latency, +etc... the time interval varies, so can't be calculated accurately. It +is possible to get a rough idea. Underpass makes the best guess it +can, and downloads a state.txt file that is close to the desired +timestamp. Using that initial state.txt file it's possible to +increment or decrement the prefix till the proper timestamp is +found. Then the prefix is used to download the data file for +processing.

+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/replicator/index.html b/Dev/replicator/index.html new file mode 100644 index 00000000..f4ef4bba --- /dev/null +++ b/Dev/replicator/index.html @@ -0,0 +1,1046 @@ + + + + + + + + + + + + + + + + + + + + + + + Underpass command line utility - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Underpass command line utility

+

underpass is a command line utility for updating databases from +changesets and change files, and runs as a system daemon. Both change +files and changesets need to be applied to the database to stay in +sync. Change data can be downloaded from planet.openstreetmap.org +every minute, and has to be applied to the databases. Data is +processed as a stream, so a large disk for temporary files or much +memory isn’t needed.

+

The primary mode is to monitor the upstream change data for new files, +and to apply them. If the timestamp specifed is in the past, the +change data files are downloaded continuously until caught up with the +current time.

+

Each data source uses a different thread for multi-core support and +better performance. As files are downloaded from the different +sources, they are analyzed, and applied to the appropriate +database. Most of the work is done by the Underpass +library. underpass is the utility program that a uses the library.

+
./underpass -h
+-h [ --help ]         display help
+-s [ --server arg]    database server (defaults to localhost)
+-m [ --monitor]       Start monitoring planet
+-t [ --timestamp arg] Starting timestamp
+-i [ --import ] arg   Initialize pgsnapshot database with datafile
+
+

By default, underpass uses the last date entered into the OSM Stats +datavase as the starting point. A different timestamp can also be +specified using --timestamp. All data files downloaded can +optionally be cached to disk, so furthur processing can use those and +save on network time.

+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/statistics/index.html b/Dev/statistics/index.html new file mode 100644 index 00000000..56f4914c --- /dev/null +++ b/Dev/statistics/index.html @@ -0,0 +1,1463 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + Statistics - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Statistics Calculations

+

Underpass process two input streams for data, but only one is used for +the initial statistics calculations. ChangeSet are +used to populate some of the columns in the database, but aren't used +during statistics calculations by the backend. Only the +OsmChange file is used, as it contains the the data +that is changed.

+

The OsmChange data file contains 3 categories of data, what was +created, modified, or deleted. Currently only changed and modified +data are used for statistics calculations.

+

All of the changed data is parsed into a data +structure +that can be passed between classes. This data structure contains all +the data as well as the associated action, create or modify. The +parsed data is then passed to the +OsmChangeFile::collectStat() +method to do the calculations. While currently part of the core code, +in the future this will be a plugin, allowing others to create +different statistics calculations without modifying the code.

+

Priority boundary

+

Currently, changes to be proccessed are filtered by ChangeSetFile::areaFilter() +and OsmChangeFile::areaFilter(), using a boundary polygon. +In some cases is not possible to say if a OsmChange is inside +the priority boundary. To disable the filtering in the replication +process, you can add the argument --osmnoboundary for OsmChanges +or --oscnoboundary for Changesets.

+

What Is Collected

+

The original statistics counted buildings, waterways, and POIs. The +new statistics break this down into two categories, accumulates +statistics for things like buildings, as well as the more detailed +representation, like what type of building it is. The list of values +is configurable, as it uses a YAML file.

+

OpenStreetMap features support a keyword and value pair. The +keywords are loosely defined, +and over time some have changed and been improved. Often new mappers +get confused, so may use keywords and values in an inconsistent +manner. Also over time the definitions of some tags has changed, or +been extended.

+

For example, let's look at schools. There is a variety of ways school +buildings are tagged. Sometimes it's building=school, with school as +the value. Sometimes school is the keyword, and the value is the type +of school. In this case, the type of school is accumulated, as well as +a generic school count. Also if building=school isn't used, then +every school also increments the count of buildings.

+

Each category of data has the total accumulated value, as well as the +more detailed breakdown. For example, it's possible to extract +statistics for only hospitals, which is a subset of all the +buildings. As keywords and values can be in different feature +categories, some are checked for in multiple ways. Some keywords and +values may be spelled differently than the default, so variations are +also looked for to be complete.

+

To find all the common tags, several continents worth of data was +analyzed to find the most common patterns for the features we want to +collect statistics for. Mixed with inconsistent tagging schemes is +random capitalization, misspellings, and international spellings. The +attempt is made to catch all reasonable variations. +TagInfo was used to find totals +of some variations, with weird tagging that was not very common gets +ignored to avoid performance impacts, and data bloat.

+

Building Types

+

Most buildings added by remote tracing of satellite imagery lack any +metadata tags beyond building=yes. When local mappers import more +detailed data, or update the existing metadata, those values get +added. This is a common set of building values.

+
    +
  • yes
    • +
  • house
    • +
  • residential
    • +
  • commercial
    • +
  • retail
    • +
  • commercial;residential
    • +
  • apartments
    • +
  • kitchen
    • +
  • roof
    • +
  • construction
    • +
  • school
    • +
  • clinic
    • +
  • hospital
    • +
  • office
    • +
  • public
    • +
  • church
    • +
  • mosque
    • +
  • temple
    • +
  • service
    • +
  • warehouse
    • +
  • industrial
    • +
  • kiosk
    • +
  • abandoned
    • +
  • cabin
    • +
  • bungalow
    • +
  • hotel
    • +
  • farm
    • +
  • hut
    • +
  • train_station
    • +
  • house_boat
    • +
  • barn
    • +
  • historic
    • +
  • latrine
    • +
  • latrines
    • +
  • toilet
    • +
  • toilets
    • +
+

Amenity Types

+

Most amenities are added by local mappers or through a data +import. Not all amenities are buildings, but for our use case that's +all that is analyzed. These are the common values for the amenity +keyword.

+
    +
  • hospital
    • +
  • school
    • +
  • clinic
    • +
  • kindergarten
    • +
  • drinking_water
    • +
  • health_facility
    • +
  • health_center
    • +
  • healthcare
    • +
+

Places Types

+

Places contain multiple features, and are mostly used to determine +local metadata improvements.

+
    +
  • village
    • +
  • hamlet
    • +
  • neighborhood
    • +
  • city
    • +
  • town
    • +
+

Highway Types

+

Highways traced from satellite imagery often lack metadata beyond the +functional type. For example, a highway that connects two villages is +easy to determine. An accumulated value for the total of highways, and +the total length in kilometers is store as an aggregate. More detailed +statistics are also kept allowing more detail when needed.

+
    +
  • trunk
    • +
  • tertiary
    • +
  • secondary
    • +
  • unclassified
    • +
  • track
    • +
  • residential
    • +
  • path
    • +
  • service
    • +
  • bridge
    • +
+

School Types

+

When school is a keyword, there are several values for the type of +school. An aggregate total of schools can be calculated, as well as detail +for the type of school.

+
    +
  • primary
    • +
  • secondary
    • +
  • kindergarten
    • +
+

Calculation Data flow

+

The data is processed by +Underpass. Underpass downloads +the changeset and the OsmChange files from the OpenStreetMap planet +server every minute. Downloaded files are also cached on disk, so it's +also possible to process data without a network connection. Once the +data is parsed from the respective data formats, it gets passed to the +OsmChangeFile::collectStat() +method. That method loops through the data structure containing the +changes to the map data. Within that method, it calls +ChangeSetFile::scanTags(), + which does all the real work. The scanTags() method uses StatsConfigSearch::search() to + search the lists of keywords and values configured at the stats configuration file. +ScanTags() returns an array of statistics for the desired features. +That array is then converted by collectStats() into the statistics data +structure, +and control returns to the processing thread.

+

The processing thread then passes the statistics data to +osmstats::applyChange(), +to insert them into the database.

+

changesets table

+

This is the primary table used to contain the data for each +changeset. All of the data is stored in a table for better query +performance on large data sets. It also limits needing SQL sub +queries or a +JOIN between +tables, reducing complexity.

+

An hstore is used to +store the statistics instead of having a separate table for each +feature to allow for more flexibility. An hstore is a key & value +pair, and multiple data items can be stored in a single column, +indexed by the key. This allows for more features to be added by the +backend and the frontend, without having modify the database schema.

+

An example query to count the total number of buildings added by the +user 4321 for a Tasking Manager project 1234 would be this:

+
+

SELECT SUM(CAST(added::hstore->'building' AS DOUBLE precision)) FROM +changesets WHERE 'hotosm-project-1234' = ANY(hashtags) AND uid=4321;

+
+

The source is the satellite imagery used for remote mapping.

+

 

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeywordDescription
idThe ID of this changeset
editorThe editor used for this changeset
uidThe OSM User ID of the mapper
created_atThe timestamp when this changes was uploaded
closed_atThe timestamp when this uploaded change completed processing
updated_atThe timestamp when this last had data updated
addedAn hstore array of the added map features
modifiedAn hstore array of the modified map features
deletedAn hstore array of the deleted map features
hashtagsAn array of the hashtags used for this changeset
sourceThe imagery source used for this changeset
bboxThe bounding box of this changeset
+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/stats-test/index.html b/Dev/stats-test/index.html new file mode 100644 index 00000000..ff8c17b4 --- /dev/null +++ b/Dev/stats-test/index.html @@ -0,0 +1,1161 @@ + + + + + + + + + + + + + + + + + + + + + + + Tests for statistics collection - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Tests for statistics collection

+

As statistics are a key feature for Underpass, there are several ways to test +results and configurations.

+

Default

+

The default test will use two files:

+
    +
  • OsmChange (testsuite/testdata/test_stats.osc)
    • +
  • Stats results validation (testsuite/testdata/test_stats.yaml)
    • +
+

./stats-test

+

More testing

+

You can run other existing tests or create your own custom ones.

+

Stats extraction from a single file

+

Extract stats from file and print the JSON result:

+

./src/testsuite/libunderpass.all/stats-test -f stats/107235440.xml

+
{
+    "added":[
+        {"highway":8},
+        {"highway_km":64917794}
+    ],
+    "modified":[
+        {"highway":8}
+    ]
+}
+
+

Stats validation from files

+

If you want to assert the results agains a YAML file, add second -f argument:

+

./src/testsuite/libunderpass.all/stats-test -f /stats/107235440.xml -f /stats/107235440.yaml

+
    PASSED: Calculating added highway
+    PASSED: Calculating modified highway
+
+

The YAML file contain the expected results:

+
- modified_highway:
+  - 8
+- added_highway:
+  - 8
+
+

Collect stats

+

Run a replicator process from timestamp, incrementing the path and collecting stats from +OsmChange files. This is useful for doing a comparison with other sources (ex: Insights DB).

+

./src/testsuite/libunderpass.all/stats-test -m collect-stats -t 2021-05-11T17:00:00 -i 10 > result.json

+

Stats configuration file

+

Stats collection can be customized using a YAML configuration file.

+

In the following example, we have an OsmChange file with several nodes created, using +building and emergency keys for tags.

+

There are two different configurations for collecting stats from that file. +On statsconfig2.yaml , building, fire_station, hospital and police +are different categories of stats.

+

./src/testsuite/libunderpass.all/stats-test -f stats/test_statsconfig.osc \ + --statsconfigfile /src/testsuite/testdata/stats/statsconfig2.yaml

+

Running the command above, you'll see this results:

+
{
+    "added":[
+        {"building":1},
+        {"fire_station":2},
+        {"hospital":2},
+        {"police":1}
+    ],
+    "modified": []
+}
+
+

You can assert this results adding another -f argument:

+

./src/testsuite/libunderpass.all/stats-test -f stats/test_statsconfig.osc \ + --statsconfigfile /src/testsuite/testdata/stats/statsconfig2.yaml \ + -f stats/test_statsconfig2.yaml

+

On the other configuration file (statsconfig3.yaml) there are two categories for stats: building and humanitarian_building.

+

If you get stats from that file:

+

./src/testsuite/libunderpass.all/stats-test -f stats/test_statsconfig.osc \ + --statsconfigfile /src/testsuite/testdata/stats/statsconfig2.yaml

+

You'll see a different result:

+
{
+    "added":[
+        {"building":2},
+        {"humanitarian_building":4}
+    ],
+    "modified": []
+}
+
+

Again, you can assert the results:

+

./src/testsuite/libunderpass.all/stats-test -f stats/test_statsconfig.osc \ + --statsconfigfile /src/testsuite/testdata/stats/statsconfig2.yaml \ + -f stats/test_statsconfig2.yaml

+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/utility/index.html b/Dev/utility/index.html new file mode 100644 index 00000000..113346fe --- /dev/null +++ b/Dev/utility/index.html @@ -0,0 +1,1312 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + Utility - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Utility Programs

+

data/setupdb.sh

+

This is a simple shell script that creates all the databases Underpass +uses. It can also be used to initialize the two internal databases +Underpass uses, one for the *.state.txt files that contain the +timestamp of the data files, and the other is for the boundaries of +countries used to determine which country a change was made in for +statistics collection. These are used to bootstrap a new Underpass +installation.

+

utils/bootstrap.sh

+ +

utils/features2yaml

+

Get tags from the Map Features OSM wiki and output YAML

+

Use this script for output a YAML data model that will be used in +the configuration files inside /validation directory.

+

Usage

+
python features2yaml.py --category buildings > buildings.yaml
+python features2yaml.py --key building:material > building:material.yaml
+python features2yaml.py --url https://wiki.openstreetmap.org/wiki/Key:landuse
+python features2yaml.py --f ../../place.html
+
+

You may want to add more configuration parameters to +the YAML file later, like geometry angles or required +tags.

+

Dependencies:

+
    +
  • pip install beautifulsoup4
    • +
  • pip install requests
    • +
+

utils/xlstoyaml

+

Convert data models from XLSForms to YAML

+

Use this script for output a YAML data model that will be used in the +configuration files inside /validation directory.

+

Usage

+
python xls2yaml.py --category buildings > buildings.yaml
+
+

You may want to add more configuration parameters to the YAML file later.

+

utils/poly2geojson

+

Converts .poly to .geojson

+

Usage

+
python poly2geojson file.poly
+
+

utils/underpassmon

+

Replication process log monitor

+

Use this script for monitoring Underpass logs and estimate replication speed.

+

You'll need to pass the -v -d parameters to the underpass command +in order to output the log file.

+

Monitoring OsmChanges processing (default):

+
python underpassmon.py -f underpass.log
+
+

Monitoring ChangeSets processing:

+
python underpassmon.py -f underpass.log -m changesets
+
+

utils/clean-osmchanges.sql

+

You may want to run this query if you're not processing raw data +and you want to just produce statistics.

+

This query deletes entries created from OsmChanges, +closed 1 day back or before , that has no corresponding Changeset.

+

We run this query every 24 hours for cleaning the database +when running the replicator process with areaFilter disabled +for osmchanges (--osmnoboundary).

+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Dev/validation/index.html b/Dev/validation/index.html new file mode 100644 index 00000000..cd1d2335 --- /dev/null +++ b/Dev/validation/index.html @@ -0,0 +1,1217 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + Validation - Underpass + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+ + + + + + + +

Validating Data

+

It is important to make sure any data being added to OpenStreetMap is +of good quality. While there are number of other tools available to do +this, Underpass data validation is oriented towards real-time +analysis. Most all of the other tools have a time delay of hours or +days. As validation can be computationally intensive, there are two +levels of validation. Since Underpass is processing change files every +minute, the data validation must also fit within that time frame. Also +the data available in the minute updates is not often complete, so +some types of validation are impossible.

+

The first level of validation is simple, checking for the proper +values for tags. For buildings, the geometry can be checked to make +sure it's got 90 degree corners or is round. Also checks for +overlapping with other buildings in the same changeset is also +done.

+

The second level can't be done on huge datasets, but works well for +smaller datasets, for example a Tasking Manager project or a +county. This other level requires access to OSM data. Since querying a +large database may not be possible within the minute timeframe, this +is only enabled for datasets country sized or smaller. Using OSM data, +it's possible to identify duplicate buildings and highways.

+

The first level of data validation is applied to all changes, since it +can be completed within a minute. The second level of validation is +focused on Tasking Manager projects. The primary goal of this +secondary validation is to catch most mapping errors right away,

+

The Database

+

All mapping errors are written to a table called validation in the +Galaxy database. This table contains the OSM ID of the feature, the +changeset ID that contains this change, and the user ID of the mapper +making the change. The status column is an array of the issues. Those +issues include bad building geometry, bad tag value, orphan node, +duplicate buildings, overlapping buildings, and incomplete +tagging. The location of the feature is a single node, which can be +used for spatial filtering.

+

In addition, there are currently two debugging columns in the +database. One is the timestamp of when the validation is performed, +and the other is the calculated angle for buildings that are +determined to have bad geometry, which is used to debug the calculation.

+

Tag Validation

+

Organized mapping campaigns, especially those done on the ground using +(ODK)[https://opendatakit.org/] based mobile tools, have a defined set +of metadata tags. Often more detailed tags are added after remote +mapping by local mappers, as it's impossible to determine some +features from the satellite imagery, like building material.

+

HOT currently has a tool called +(MapCampaigner)[https://campaigns-staging.hotosm.org/], that is used +to validate tag completeness. Required tags are defined in a +(YAML)[https://www.yaml.org] config file. For example, to completely +map a building, the material of the walls of the building, the +material used for a roof, and whether it has walls. If the building is +an amenity, it should have a name and the type of amenity. The +existing list of tag values were based on what MapCampaigner uses, and +then extended by the Data Quality team at HOT. The current values are +listed in the config files:

+

amenities, + buildings, + highways, + solid waste, + landuse

+

By default, tag completeness is not enabled, as any data added by +remote mapping will always be missing tags, or have different +permissible values. Instead tag completeness can be used to monitor a +ground mapping campaign.

+

Bad Geometry

+

Often buildings are added that don't have square corners. This can be +eliminated by using a plugin for some map editors like JOSM to force +all new buildings to have the correct geometry. There are other +plugins that allow the mapper or validator to correct the +geometry. Flagging this error while the mapper is still active allows +for educating the mapper about this issue so they can improve their +quality, which might be as simple as having them use a building +plugin.

+

To determine the building correctness, a corner is chosen, and the +angle between the two lines is calculated, A threshold is then applied +so any building that looks rectangular to the user is considered +acceptable. That threshold value is in the YAML file for building +validation so it's easy to adjust.

+

Since Underpass is using minute change files, sometimes it's difficult +to validate buildings that have been edited, as not all the nodes in +the building polygon are in the change file. Most remote mapping only +adds buildings, any editing is done later by a human validator.

+

Highway Validation

+

Validating highways starts the correct tag value. More than validating +the values for the highway tag, this also will check the values of +important tags, like surface, smoothness, tracktype, and +sac_scale. The important validation is making sure any new highway +actually connects to the highway network. Otherwise navigation doesn't +work.

+ + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/Doxyfile.in b/Doxyfile.in new file mode 100644 index 00000000..74b5134c --- /dev/null +++ b/Doxyfile.in @@ -0,0 +1,2561 @@ +# Doxyfile 1.8.20 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project. +# +# All text after a double hash (##) is considered a comment and is placed in +# front of the TAG it is preceding. +# +# All text after a single hash (#) is considered a comment and will be ignored. +# The format is: +# TAG = value [value, ...] +# For lists, items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (\" \"). + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the configuration +# file that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# https://www.gnu.org/software/libiconv/ for the list of possible encodings. +# The default value is: UTF-8. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by +# double-quotes, unless you are using Doxywizard) that should identify the +# project for which the documentation is generated. This name is used in the +# title of most generated pages and in a few other places. +# The default value is: My Project. + +PROJECT_NAME = "Underpass" + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. This +# could be handy for archiving the generated documentation or if some version +# control system is used. + +PROJECT_NUMBER = + +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer a +# quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF = + +# With the PROJECT_LOGO tag one can specify a logo or an icon that is included +# in the documentation. The maximum height of the logo should not exceed 55 +# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy +# the logo to the output directory. + +PROJECT_LOGO = + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path +# into which the generated documentation will be written. If a relative path is +# entered, it will be relative to the location where doxygen was started. If +# left blank the current directory will be used. + +OUTPUT_DIRECTORY = + +# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- +# directories (in 2 levels) under the output directory of each output format and +# will distribute the generated files over these directories. Enabling this +# option can be useful when feeding doxygen a huge amount of source files, where +# putting all generated files in the same directory would otherwise causes +# performance problems for the file system. +# The default value is: NO. + +CREATE_SUBDIRS = NO + +# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# characters to appear in the names of generated files. If set to NO, non-ASCII +# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode +# U+3044. +# The default value is: NO. + +ALLOW_UNICODE_NAMES = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, +# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), +# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, +# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), +# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, +# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, +# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, +# Ukrainian and Vietnamese. +# The default value is: English. + +OUTPUT_LANGUAGE = English + +# The OUTPUT_TEXT_DIRECTION tag is used to specify the direction in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all generated output in the proper direction. +# Possible values are: None, LTR, RTL and Context. +# The default value is: None. + +OUTPUT_TEXT_DIRECTION = None + +# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member +# descriptions after the members that are listed in the file and class +# documentation (similar to Javadoc). Set to NO to disable this. +# The default value is: YES. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief +# description of a member or function before the detailed description +# +# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. +# The default value is: YES. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator that is +# used to form the text in various listings. Each string in this list, if found +# as the leading text of the brief description, will be stripped from the text +# and the result, after processing the whole list, is used as the annotated +# text. Otherwise, the brief description is used as-is. If left blank, the +# following values are used ($name is automatically replaced with the name of +# the entity):The $name class, The $name widget, The $name file, is, provides, +# specifies, contains, represents, a, an and the. + +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# doxygen will generate a detailed section even if there is only a brief +# description. +# The default value is: NO. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. +# The default value is: NO. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path +# before files name in the file list and in the header files. If set to NO the +# shortest path that makes the file name unique will be used +# The default value is: YES. + +FULL_PATH_NAMES = YES + +# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. +# Stripping is only done if one of the specified strings matches the left-hand +# part of the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the path to +# strip. +# +# Note that you can specify absolute paths here, but also relative paths, which +# will be relative from the directory where doxygen is started. +# This tag requires that the tag FULL_PATH_NAMES is set to YES. + +STRIP_FROM_PATH = + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the +# path mentioned in the documentation of a class, which tells the reader which +# header file to include in order to use a class. If left blank only the name of +# the header file containing the class definition is used. Otherwise one should +# specify the list of include paths that are normally passed to the compiler +# using the -I flag. + +STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but +# less readable) file names. This can be useful is your file systems doesn't +# support long names like on DOS, Mac, or CD-ROM. +# The default value is: NO. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the +# first line (until the first dot) of a Javadoc-style comment as the brief +# description. If set to NO, the Javadoc-style will behave just like regular Qt- +# style comments (thus requiring an explicit @brief command for a brief +# description.) +# The default value is: NO. + +JAVADOC_AUTOBRIEF = NO + +# If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line +# such as +# /*************** +# as being the beginning of a Javadoc-style comment "banner". If set to NO, the +# Javadoc-style will behave just like regular comments and it will not be +# interpreted by doxygen. +# The default value is: NO. + +JAVADOC_BANNER = NO + +# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first +# line (until the first dot) of a Qt-style comment as the brief description. If +# set to NO, the Qt-style will behave just like regular Qt-style comments (thus +# requiring an explicit \brief command for a brief description.) +# The default value is: NO. + +QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a +# multi-line C++ special comment block (i.e. a block of //! or /// comments) as +# a brief description. This used to be the default behavior. The new default is +# to treat a multi-line C++ comment block as a detailed description. Set this +# tag to YES if you prefer the old behavior instead. +# +# Note that setting this tag to YES also means that rational rose comments are +# not recognized any more. +# The default value is: NO. + +MULTILINE_CPP_IS_BRIEF = NO + +# By default Python docstrings are displayed as preformatted text and doxygen's +# special commands cannot be used. By setting PYTHON_DOCSTRING to NO the +# doxygen's special commands can be used and the contents of the docstring +# documentation blocks is shown as doxygen documentation. +# The default value is: YES. + +PYTHON_DOCSTRING = YES + +# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the +# documentation from any documented member that it re-implements. +# The default value is: YES. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new +# page for each member. If set to NO, the documentation of a member will be part +# of the file/class/namespace that contains it. +# The default value is: NO. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen +# uses this value to replace tabs by spaces in code fragments. +# Minimum value: 1, maximum value: 16, default value: 4. + +TAB_SIZE = 4 + +# This tag can be used to specify a number of aliases that act as commands in +# the documentation. An alias has the form: +# name=value +# For example adding +# "sideeffect=@par Side Effects:\n" +# will allow you to put the command \sideeffect (or @sideeffect) in the +# documentation, which will result in a user-defined paragraph with heading +# "Side Effects:". You can put \n's in the value part of an alias to insert +# newlines (in the resulting output). You can put ^^ in the value part of an +# alias to insert a newline as if a physical newline was in the original file. +# When you need a literal { or } or , in the value part of an alias you have to +# escape them by means of a backslash (\), this can lead to conflicts with the +# commands \{ and \} for these it is advised to use the version @{ and @} or use +# a double escape (\\{ and \\}) + +ALIASES = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources +# only. Doxygen will then generate output that is more tailored for C. For +# instance, some of the names that are used will be different. The list of all +# members will be omitted, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_FOR_C = NO + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or +# Python sources only. Doxygen will then generate output that is more tailored +# for that language. For instance, namespaces will be presented as packages, +# qualified scopes will look different, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources. Doxygen will then generate output that is tailored for Fortran. +# The default value is: NO. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for VHDL. +# The default value is: NO. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Set the OPTIMIZE_OUTPUT_SLICE tag to YES if your project consists of Slice +# sources only. Doxygen will then generate output that is more tailored for that +# language. For instance, namespaces will be presented as modules, types will be +# separated into more groups, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_SLICE = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given +# extension. Doxygen has a built-in mapping, but you can override or extend it +# using this tag. The format is ext=language, where ext is a file extension, and +# language is one of the parsers supported by doxygen: IDL, Java, JavaScript, +# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, VHDL, +# Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: +# FortranFree, unknown formatted Fortran: Fortran. In the later case the parser +# tries to guess whether the code is fixed or free formatted code, this is the +# default for Fortran type files). For instance to make doxygen treat .inc files +# as Fortran files (default is PHP), and .f files as C (default is Fortran), +# use: inc=Fortran f=C. +# +# Note: For files without extension you can use no_extension as a placeholder. +# +# Note that for custom extensions you also need to set FILE_PATTERNS otherwise +# the files are not read by doxygen. + +EXTENSION_MAPPING = + +# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments +# according to the Markdown format, which allows for more readable +# documentation. See https://daringfireball.net/projects/markdown/ for details. +# The output of markdown processing is further processed by doxygen, so you can +# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in +# case of backward compatibilities issues. +# The default value is: YES. + +MARKDOWN_SUPPORT = YES + +# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up +# to that level are automatically included in the table of contents, even if +# they do not have an id attribute. +# Note: This feature currently applies only to Markdown headings. +# Minimum value: 0, maximum value: 99, default value: 5. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +TOC_INCLUDE_HEADINGS = 5 + +# When enabled doxygen tries to link words that correspond to documented +# classes, or namespaces to their corresponding documentation. Such a link can +# be prevented in individual cases by putting a % sign in front of the word or +# globally by setting AUTOLINK_SUPPORT to NO. +# The default value is: YES. + +AUTOLINK_SUPPORT = YES + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should set this +# tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); +# versus func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. +# The default value is: NO. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. +# The default value is: NO. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip (see: +# https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen +# will parse them like normal C++ but will assume all classes use public instead +# of private inheritance when no explicit protection keyword is present. +# The default value is: NO. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate +# getter and setter methods for a property. Setting this option to YES will make +# doxygen to replace the get and set methods by a property in the documentation. +# This will only work if the methods are indeed getting or setting a simple +# type. If this is not the case, or you want to show the methods anyway, you +# should set this option to NO. +# The default value is: YES. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. +# The default value is: NO. + +DISTRIBUTE_GROUP_DOC = NO + +# If one adds a struct or class to a group and this option is enabled, then also +# any nested class or struct is added to the same group. By default this option +# is disabled and one has to add nested compounds explicitly via \ingroup. +# The default value is: NO. + +GROUP_NESTED_COMPOUNDS = NO + +# Set the SUBGROUPING tag to YES to allow class member groups of the same type +# (for instance a group of public functions) to be put as a subgroup of that +# type (e.g. under the Public Functions section). Set it to NO to prevent +# subgrouping. Alternatively, this can be done per class using the +# \nosubgrouping command. +# The default value is: YES. + +SUBGROUPING = YES + +# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions +# are shown inside the group in which they are included (e.g. using \ingroup) +# instead of on a separate page (for HTML and Man pages) or section (for LaTeX +# and RTF). +# +# Note that this feature does not work in combination with +# SEPARATE_MEMBER_PAGES. +# The default value is: NO. + +INLINE_GROUPED_CLASSES = NO + +# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions +# with only public data fields or simple typedef fields will be shown inline in +# the documentation of the scope in which they are defined (i.e. file, +# namespace, or group documentation), provided this scope is documented. If set +# to NO, structs, classes, and unions are shown on a separate page (for HTML and +# Man pages) or section (for LaTeX and RTF). +# The default value is: NO. + +INLINE_SIMPLE_STRUCTS = NO + +# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or +# enum is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically be +# useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. +# The default value is: NO. + +TYPEDEF_HIDES_STRUCT = NO + +# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This +# cache is used to resolve symbols given their name and scope. Since this can be +# an expensive process and often the same symbol appears multiple times in the +# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small +# doxygen will become slower. If the cache is too large, memory is wasted. The +# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range +# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 +# symbols. At the end of a run doxygen will report the cache usage and suggest +# the optimal cache size from a speed point of view. +# Minimum value: 0, maximum value: 9, default value: 0. + +LOOKUP_CACHE_SIZE = 0 + +# The NUM_PROC_THREADS specifies the number threads doxygen is allowed to use +# during processing. When set to 0 doxygen will based this on the number of +# cores available in the system. You can set it explicitly to a value larger +# than 0 to get more control over the balance between CPU load and processing +# speed. At this moment only the input processing can be done using multiple +# threads. Since this is still an experimental feature the default is set to 1, +# which efficively disables parallel processing. Please report any issues you +# encounter. Generating dot graphs in parallel is controlled by the +# DOT_NUM_THREADS setting. +# Minimum value: 0, maximum value: 32, default value: 1. + +NUM_PROC_THREADS = 1 + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in +# documentation are documented, even if no documentation was available. Private +# class members and static file members will be hidden unless the +# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. +# Note: This will also disable the warnings about undocumented members that are +# normally produced when WARNINGS is set to YES. +# The default value is: NO. + +EXTRACT_ALL = NO + +# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will +# be included in the documentation. +# The default value is: NO. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual +# methods of a class will be included in the documentation. +# The default value is: NO. + +EXTRACT_PRIV_VIRTUAL = NO + +# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal +# scope will be included in the documentation. +# The default value is: NO. + +EXTRACT_PACKAGE = NO + +# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be +# included in the documentation. +# The default value is: NO. + +EXTRACT_STATIC = NO + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined +# locally in source files will be included in the documentation. If set to NO, +# only classes defined in header files are included. Does not have any effect +# for Java sources. +# The default value is: YES. + +EXTRACT_LOCAL_CLASSES = YES + +# This flag is only useful for Objective-C code. If set to YES, local methods, +# which are defined in the implementation section but not in the interface are +# included in the documentation. If set to NO, only methods in the interface are +# included. +# The default value is: NO. + +EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base name of +# the file that contains the anonymous namespace. By default anonymous namespace +# are hidden. +# The default value is: NO. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all +# undocumented members inside documented classes or files. If set to NO these +# members will be included in the various overviews, but no documentation +# section is generated. This option has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. If set +# to NO, these classes will be included in the various overviews. This option +# has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend +# declarations. If set to NO, these declarations will be included in the +# documentation. +# The default value is: NO. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any +# documentation blocks found inside the body of a function. If set to NO, these +# blocks will be appended to the function's detailed documentation block. +# The default value is: NO. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation that is typed after a +# \internal command is included. If the tag is set to NO then the documentation +# will be excluded. Set it to YES to include the internal documentation. +# The default value is: NO. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file +# names in lower-case letters. If set to YES, upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# (including Cygwin) and Mac users are advised to set this option to NO. +# The default value is: system dependent. + +CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with +# their full class and namespace scopes in the documentation. If set to YES, the +# scope will be hidden. +# The default value is: NO. + +HIDE_SCOPE_NAMES = NO + +# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will +# append additional text to a page's title, such as Class Reference. If set to +# YES the compound reference will be hidden. +# The default value is: NO. + +HIDE_COMPOUND_REFERENCE= NO + +# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of +# the files that are included by a file in the documentation of that file. +# The default value is: YES. + +SHOW_INCLUDE_FILES = YES + +# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each +# grouped member an include statement to the documentation, telling the reader +# which file to include in order to use the member. +# The default value is: NO. + +SHOW_GROUPED_MEMB_INC = NO + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include +# files with double quotes in the documentation rather than with sharp brackets. +# The default value is: NO. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the +# documentation for inline members. +# The default value is: YES. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the +# (detailed) documentation of file and class members alphabetically by member +# name. If set to NO, the members will appear in declaration order. +# The default value is: YES. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief +# descriptions of file, namespace and class members alphabetically by member +# name. If set to NO, the members will appear in declaration order. Note that +# this will also influence the order of the classes in the class list. +# The default value is: NO. + +SORT_BRIEF_DOCS = NO + +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the +# (brief and detailed) documentation of class members so that constructors and +# destructors are listed first. If set to NO the constructors will appear in the +# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. +# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief +# member documentation. +# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting +# detailed member documentation. +# The default value is: NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy +# of group names into alphabetical order. If set to NO the group names will +# appear in their defined order. +# The default value is: NO. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by +# fully-qualified names, including namespaces. If set to NO, the class list will +# be sorted only by class name, not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the alphabetical +# list. +# The default value is: NO. + +SORT_BY_SCOPE_NAME = NO + +# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper +# type resolution of all parameters of a function it will reject a match between +# the prototype and the implementation of a member function even if there is +# only one candidate or it is obvious which candidate to choose by doing a +# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still +# accept a match between prototype and implementation in such cases. +# The default value is: NO. + +STRICT_PROTO_MATCHING = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo +# list. This list is created by putting \todo commands in the documentation. +# The default value is: YES. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test +# list. This list is created by putting \test commands in the documentation. +# The default value is: YES. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug +# list. This list is created by putting \bug commands in the documentation. +# The default value is: YES. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) +# the deprecated list. This list is created by putting \deprecated commands in +# the documentation. +# The default value is: YES. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional documentation +# sections, marked by \if ... \endif and \cond +# ... \endcond blocks. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the +# initial value of a variable or macro / define can have for it to appear in the +# documentation. If the initializer consists of more lines than specified here +# it will be hidden. Use a value of 0 to hide initializers completely. The +# appearance of the value of individual variables and macros / defines can be +# controlled using \showinitializer or \hideinitializer command in the +# documentation regardless of this setting. +# Minimum value: 0, maximum value: 10000, default value: 30. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at +# the bottom of the documentation of classes and structs. If set to YES, the +# list will mention the files that were used to generate the documentation. +# The default value is: YES. + +SHOW_USED_FILES = YES + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This +# will remove the Files entry from the Quick Index and from the Folder Tree View +# (if specified). +# The default value is: YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces +# page. This will remove the Namespaces entry from the Quick Index and from the +# Folder Tree View (if specified). +# The default value is: YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command command input-file, where command is the value of the +# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided +# by doxygen. Whatever the program writes to standard output is used as the file +# version. For an example see the documentation. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. To create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. You can +# optionally specify a file name after the option, if omitted DoxygenLayout.xml +# will be used as the name of the layout file. +# +# Note that if you run doxygen from a directory containing a file called +# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE +# tag is left empty. + +LAYOUT_FILE = + +# The CITE_BIB_FILES tag can be used to specify one or more bib files containing +# the reference definitions. This must be a list of .bib files. The .bib +# extension is automatically appended if omitted. This requires the bibtex tool +# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info. +# For LaTeX the style of the bibliography can be controlled using +# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the +# search path. See also \cite for info how to create references. + +CITE_BIB_FILES = + +#--------------------------------------------------------------------------- +# Configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated to +# standard output by doxygen. If QUIET is set to YES this implies that the +# messages are off. +# The default value is: NO. + +QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES +# this implies that the warnings are on. +# +# Tip: Turn warnings on while writing the documentation. +# The default value is: YES. + +WARNINGS = YES + +# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate +# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: YES. + +WARN_IF_UNDOCUMENTED = YES + +# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some parameters +# in a documented function, or documenting parameters that don't exist or using +# markup commands wrongly. +# The default value is: YES. + +WARN_IF_DOC_ERROR = YES + +# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that +# are documented, but have no documentation for their parameters or return +# value. If set to NO, doxygen will only warn about wrong or incomplete +# parameter documentation, but not about the absence of documentation. If +# EXTRACT_ALL is set to YES then this flag will automatically be disabled. +# The default value is: NO. + +WARN_NO_PARAMDOC = NO + +# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when +# a warning is encountered. +# The default value is: NO. + +WARN_AS_ERROR = NO + +# The WARN_FORMAT tag determines the format of the warning messages that doxygen +# can produce. The string should contain the $file, $line, and $text tags, which +# will be replaced by the file and line number from which the warning originated +# and the warning text. Optionally the format may contain $version, which will +# be replaced by the version of the file (if it could be obtained via +# FILE_VERSION_FILTER) +# The default value is: $file:$line: $text. + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning and error +# messages should be written. If left blank the output is written to standard +# error (stderr). + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# Configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag is used to specify the files and/or directories that contain +# documented source files. You may enter file names like myfile.cpp or +# directories like /usr/src/myproject. Separate the files or directories with +# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING +# Note: If this tag is empty the current directory is searched. + +INPUT = @SRCDIR@ + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses +# libiconv (or the iconv built into libc) for the transcoding. See the libiconv +# documentation (see: https://www.gnu.org/software/libiconv/) for the list of +# possible encodings. +# The default value is: UTF-8. + +INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and +# *.h) to filter out the source-files in the directories. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# read by doxygen. +# +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, +# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, +# *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, +# *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C comment), +# *.doc (to be provided as doxygen C comment), *.txt (to be provided as doxygen +# C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, +# *.vhdl, *.ucf, *.qsf and *.ice. + +FILE_PATTERNS = *.c \ + *.cc \ + *.h \ + *.hh \ + *.md \ + *.txt \ + *.py + +# The RECURSIVE tag can be used to specify whether or not subdirectories should +# be searched for input files as well. +# The default value is: NO. + +RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should be +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. +# +# Note that relative paths are relative to the directory from which doxygen is +# run. + +EXCLUDE = @SRCDIR@/util @SRCDIR@/example @SRCDIR@/raw @SRCDIR@/testsuite + +# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or +# directories that are symbolic links (a Unix file system feature) are excluded +# from the input. +# The default value is: NO. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories for example use the pattern */test/* + +EXCLUDE_PATTERNS = + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories use the pattern */test/* + +EXCLUDE_SYMBOLS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or directories +# that contain example code fragments that are included (see the \include +# command). + +EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank all +# files are included. + +EXAMPLE_PATTERNS = * + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude commands +# irrespective of the value of the RECURSIVE tag. +# The default value is: NO. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or directories +# that contain images that are to be included in the documentation (see the +# \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command: +# +# +# +# where is the value of the INPUT_FILTER tag, and is the +# name of an input file. Doxygen will then use the output that the filter +# program writes to standard output. If FILTER_PATTERNS is specified, this tag +# will be ignored. +# +# Note that the filter must not add or remove lines; it is applied before the +# code is scanned, but not when the output code is generated. If lines are added +# or removed, the anchors will not be placed correctly. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: pattern=filter +# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how +# filters are used. If the FILTER_PATTERNS tag is empty or if none of the +# patterns match the file name, INPUT_FILTER is applied. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will also be used to filter the input files that are used for +# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). +# The default value is: NO. + +FILTER_SOURCE_FILES = NO + +# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file +# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and +# it is also possible to disable source filtering for a specific pattern using +# *.ext= (so without naming a filter). +# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. + +FILTER_SOURCE_PATTERNS = + +# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that +# is part of the input, its contents will be placed on the main page +# (index.html). This can be useful if you have a project on for instance GitHub +# and want to reuse the introduction page also for the doxygen output. + +USE_MDFILE_AS_MAINPAGE = @SRCDIR@/README.md + +#--------------------------------------------------------------------------- +# Configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will be +# generated. Documented entities will be cross-referenced with these sources. +# +# Note: To get rid of all source code in the generated output, make sure that +# also VERBATIM_HEADERS is set to NO. +# The default value is: NO. + +SOURCE_BROWSER = NO + +# Setting the INLINE_SOURCES tag to YES will include the body of functions, +# classes and enums directly into the documentation. +# The default value is: NO. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any +# special comment blocks from generated source code fragments. Normal C, C++ and +# Fortran comments will always remain visible. +# The default value is: YES. + +STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES then for each documented +# entity all documented functions referencing it will be listed. +# The default value is: NO. + +REFERENCED_BY_RELATION = NO + +# If the REFERENCES_RELATION tag is set to YES then for each documented function +# all documented entities called/used by that function will be listed. +# The default value is: NO. + +REFERENCES_RELATION = NO + +# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set +# to YES then the hyperlinks from functions in REFERENCES_RELATION and +# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will +# link to the documentation. +# The default value is: YES. + +REFERENCES_LINK_SOURCE = YES + +# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the +# source code will show a tooltip with additional information such as prototype, +# brief description and links to the definition and documentation. Since this +# will make the HTML file larger and loading of large files a bit slower, you +# can opt to disable this feature. +# The default value is: YES. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +SOURCE_TOOLTIPS = YES + +# If the USE_HTAGS tag is set to YES then the references to source code will +# point to the HTML generated by the htags(1) tool instead of doxygen built-in +# source browser. The htags tool is part of GNU's global source tagging system +# (see https://www.gnu.org/software/global/global.html). You will need version +# 4.8.6 or higher. +# +# To use it do the following: +# - Install the latest version of global +# - Enable SOURCE_BROWSER and USE_HTAGS in the configuration file +# - Make sure the INPUT points to the root of the source tree +# - Run doxygen as normal +# +# Doxygen will invoke htags (and that will in turn invoke gtags), so these +# tools must be available from the command line (i.e. in the search path). +# +# The result: instead of the source browser generated by doxygen, the links to +# source code will now point to the output of htags. +# The default value is: NO. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a +# verbatim copy of the header file for each class for which an include is +# specified. Set to NO to disable this. +# See also: Section \class. +# The default value is: YES. + +VERBATIM_HEADERS = YES + +# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the +# clang parser (see: http://clang.llvm.org/) for more accurate parsing at the +# cost of reduced performance. This can be particularly helpful with template +# rich C++ code for which doxygen's built-in parser lacks the necessary type +# information. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. +# The default value is: NO. + +CLANG_ASSISTED_PARSING = NO + +# If clang assisted parsing is enabled you can provide the compiler with command +# line options that you would normally use when invoking the compiler. Note that +# the include paths will already be set by doxygen for the files and directories +# specified with INPUT and INCLUDE_PATH. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_OPTIONS = + +# If clang assisted parsing is enabled you can provide the clang parser with the +# path to the directory containing a file called compile_commands.json. This +# file is the compilation database (see: +# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the +# options used when the source files were built. This is equivalent to +# specifying the "-p" option to a clang tool, such as clang-check. These options +# will then be passed to the parser. Any options specified with CLANG_OPTIONS +# will be added as well. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. + +CLANG_DATABASE_PATH = + +#--------------------------------------------------------------------------- +# Configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all +# compounds will be generated. Enable this if the project contains a lot of +# classes, structs, unions or interfaces. +# The default value is: YES. + +ALPHABETICAL_INDEX = YES + +# In case all classes in a project start with a common prefix, all classes will +# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag +# can be used to specify a prefix (or a list of prefixes) that should be ignored +# while generating the index headers. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output +# The default value is: YES. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: html. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_OUTPUT = html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each +# generated HTML page (for example: .htm, .php, .asp). +# The default value is: .html. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a user-defined HTML header file for +# each generated HTML page. If the tag is left blank doxygen will generate a +# standard header. +# +# To get valid HTML the header file that includes any scripts and style sheets +# that doxygen needs, which is dependent on the configuration options used (e.g. +# the setting GENERATE_TREEVIEW). It is highly recommended to start with a +# default header using +# doxygen -w html new_header.html new_footer.html new_stylesheet.css +# YourConfigFile +# and then modify the file new_header.html. See also section "Doxygen usage" +# for information on how to generate the default header that doxygen normally +# uses. +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. For a description +# of the possible markers and block names see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each +# generated HTML page. If the tag is left blank doxygen will generate a standard +# footer. See HTML_HEADER for more information on how to generate a default +# footer and what special commands can be used inside the footer. See also +# section "Doxygen usage" for information on how to generate the default footer +# that doxygen normally uses. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style +# sheet that is used by each HTML page. It can be used to fine-tune the look of +# the HTML output. If left blank doxygen will generate a default style sheet. +# See also section "Doxygen usage" for information on how to generate the style +# sheet that doxygen normally uses. +# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as +# it is more robust and this tag (HTML_STYLESHEET) will in the future become +# obsolete. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_STYLESHEET = + +# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# cascading style sheets that are included after the standard style sheets +# created by doxygen. Using this option one can overrule certain style aspects. +# This is preferred over using HTML_STYLESHEET since it does not replace the +# standard style sheet and is therefore more robust against future updates. +# Doxygen will copy the style sheet files to the output directory. +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the +# list). For an example see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_STYLESHEET = + +# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the HTML output directory. Note +# that these files will be copied to the base HTML output directory. Use the +# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these +# files. In the HTML_STYLESHEET file, use the file name only. Also note that the +# files will be copied as-is; there are no commands or markers available. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_FILES = + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen +# will adjust the colors in the style sheet and background images according to +# this color. Hue is specified as an angle on a colorwheel, see +# https://en.wikipedia.org/wiki/Hue for more information. For instance the value +# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 +# purple, and 360 is red again. +# Minimum value: 0, maximum value: 359, default value: 220. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors +# in the HTML output. For a value of 0 the output will use grayscales only. A +# value of 255 will produce the most vivid colors. +# Minimum value: 0, maximum value: 255, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the +# luminance component of the colors in the HTML output. Values below 100 +# gradually make the output lighter, whereas values above 100 make the output +# darker. The value divided by 100 is the actual gamma applied, so 80 represents +# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not +# change the gamma. +# Minimum value: 40, maximum value: 240, default value: 80. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting this +# to YES can help to show when doxygen was last run and thus if the +# documentation is up to date. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_TIMESTAMP = NO + +# If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML +# documentation will contain a main index with vertical navigation menus that +# are dynamically created via JavaScript. If disabled, the navigation index will +# consists of multiple levels of tabs that are statically embedded in every HTML +# page. Disable this option to support browsers that do not have JavaScript, +# like the Qt help browser. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_MENUS = YES + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_SECTIONS = NO + +# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries +# shown in the various tree structured indices initially; the user can expand +# and collapse entries dynamically later on. Doxygen will expand the tree to +# such a level that at most the specified number of entries are visible (unless +# a fully collapsed tree already exceeds this amount). So setting the number of +# entries 1 will produce a full collapsed tree by default. 0 is a special value +# representing an infinite number of entries and will result in a full expanded +# tree by default. +# Minimum value: 0, maximum value: 9999, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_INDEX_NUM_ENTRIES = 100 + +# If the GENERATE_DOCSET tag is set to YES, additional index files will be +# generated that can be used as input for Apple's Xcode 3 integrated development +# environment (see: https://developer.apple.com/xcode/), introduced with OSX +# 10.5 (Leopard). To create a documentation set, doxygen will generate a +# Makefile in the HTML output directory. Running make will produce the docset in +# that directory and running make install will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at +# startup. See https://developer.apple.com/library/archive/featuredarticles/Doxy +# genXcode/_index.html for more information. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_DOCSET = NO + +# This tag determines the name of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# The default value is: Doxygen generated docs. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# This tag specifies a string that should uniquely identify the documentation +# set bundle. This should be a reverse domain-name style string, e.g. +# com.mycompany.MyDocSet. Doxygen will append .docset to the name. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. +# The default value is: org.doxygen.Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. +# The default value is: Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three +# additional HTML index files: index.hhp, index.hhc, and index.hhk. The +# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop +# (see: https://www.microsoft.com/en-us/download/details.aspx?id=21138) on +# Windows. +# +# The HTML Help Workshop contains a compiler that can convert all HTML output +# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML +# files are now used as the Windows 98 help format, and will replace the old +# Windows help format (.hlp) on all Windows platforms in the future. Compressed +# HTML files also contain an index, a table of contents, and you can search for +# words in the documentation. The HTML workshop also contains a viewer for +# compressed HTML files. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_HTMLHELP = NO + +# The CHM_FILE tag can be used to specify the file name of the resulting .chm +# file. You can add a path in front of the file if the result should not be +# written to the html output directory. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +CHM_FILE = + +# The HHC_LOCATION tag can be used to specify the location (absolute path +# including file name) of the HTML help compiler (hhc.exe). If non-empty, +# doxygen will try to run the HTML help compiler on the generated index.hhp. +# The file has to be specified with full path. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +HHC_LOCATION = + +# The GENERATE_CHI flag controls if a separate .chi index file is generated +# (YES) or that it should be included in the main .chm file (NO). +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +GENERATE_CHI = NO + +# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) +# and project file content. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +CHM_INDEX_ENCODING = + +# The BINARY_TOC flag controls whether a binary table of contents is generated +# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it +# enables the Previous and Next buttons. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members to +# the table of contents of the HTML help documentation and to the tree view. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +TOC_EXPAND = NO + +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that +# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help +# (.qch) of the generated HTML documentation. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify +# the file name of the resulting .qch file. The path specified is relative to +# the HTML output folder. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help +# Project output. For more information please see Qt Help Project / Namespace +# (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace). +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt +# Help Project output. For more information please see Qt Help Project / Virtual +# Folders (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual- +# folders). +# The default value is: doc. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_VIRTUAL_FOLDER = doc + +# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom +# filter to add. For more information please see Qt Help Project / Custom +# Filters (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom- +# filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see Qt Help Project / Custom +# Filters (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom- +# filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's filter section matches. Qt Help Project / Filter Attributes (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#filter-attributes). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_SECT_FILTER_ATTRS = + +# The QHG_LOCATION tag can be used to specify the location of Qt's +# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the +# generated .qhp file. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be +# generated, together with the HTML files, they form an Eclipse help plugin. To +# install this plugin and make it available under the help contents menu in +# Eclipse, the contents of the directory containing the HTML and XML files needs +# to be copied into the plugins directory of eclipse. The name of the directory +# within the plugins directory should be the same as the ECLIPSE_DOC_ID value. +# After copying Eclipse needs to be restarted before the help appears. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the Eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have this +# name. Each documentation set should have its own identifier. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# If you want full control over the layout of the generated HTML pages it might +# be necessary to disable the index and replace it with your own. The +# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top +# of each HTML page. A value of NO enables the index and the value YES disables +# it. Since the tabs in the index contain the same information as the navigation +# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +DISABLE_INDEX = NO + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. If the tag +# value is set to YES, a side panel will be generated containing a tree-like +# index structure (just like the one that is generated for HTML Help). For this +# to work a browser that supports JavaScript, DHTML, CSS and frames is required +# (i.e. any modern browser). Windows users are probably better off using the +# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can +# further fine-tune the look of the index. As an example, the default style +# sheet generated by doxygen has an example that shows how to put an image at +# the root of the tree instead of the PROJECT_NAME. Since the tree basically has +# the same information as the tab index, you could consider setting +# DISABLE_INDEX to YES when enabling this option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_TREEVIEW = NO + +# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that +# doxygen will group on one line in the generated HTML documentation. +# +# Note that a value of 0 will completely suppress the enum values from appearing +# in the overview section. +# Minimum value: 0, maximum value: 20, default value: 4. +# This tag requires that the tag GENERATE_HTML is set to YES. + +ENUM_VALUES_PER_LINE = 4 + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used +# to set the initial width (in pixels) of the frame in which the tree is shown. +# Minimum value: 0, maximum value: 1500, default value: 250. +# This tag requires that the tag GENERATE_HTML is set to YES. + +TREEVIEW_WIDTH = 250 + +# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to +# external symbols imported via tag files in a separate window. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +EXT_LINKS_IN_WINDOW = NO + +# If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg +# tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see +# https://inkscape.org) to generate formulas as SVG images instead of PNGs for +# the HTML output. These images will generally look nicer at scaled resolutions. +# Possible values are: png (the default) and svg (looks nicer but requires the +# pdf2svg or inkscape tool). +# The default value is: png. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FORMULA_FORMAT = png + +# Use this tag to change the font size of LaTeX formulas included as images in +# the HTML documentation. When you change the font size after a successful +# doxygen run you need to manually remove any form_*.png images from the HTML +# output directory to force them to be regenerated. +# Minimum value: 8, maximum value: 50, default value: 10. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANSPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are not +# supported properly for IE 6.0, but are supported on all modern browsers. +# +# Note that when changing this option you need to delete any form_*.png files in +# the HTML output directory before the changes have effect. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_TRANSPARENT = YES + +# The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands +# to create new LaTeX commands to be used in formulas as building blocks. See +# the section "Including formulas" for details. + +FORMULA_MACROFILE = + +# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see +# https://www.mathjax.org) which uses client side JavaScript for the rendering +# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX +# installed or if you want to formulas look prettier in the HTML output. When +# enabled you may also need to install MathJax separately and configure the path +# to it using the MATHJAX_RELPATH option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +USE_MATHJAX = NO + +# When MathJax is enabled you can set the default output format to be used for +# the MathJax output. See the MathJax site (see: +# http://docs.mathjax.org/en/latest/output.html) for more details. +# Possible values are: HTML-CSS (which is slower, but has the best +# compatibility), NativeMML (i.e. MathML) and SVG. +# The default value is: HTML-CSS. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_FORMAT = HTML-CSS + +# When MathJax is enabled you need to specify the location relative to the HTML +# output directory using the MATHJAX_RELPATH option. The destination directory +# should contain the MathJax.js script. For instance, if the mathjax directory +# is located at the same level as the HTML output directory, then +# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax +# Content Delivery Network so you can quickly see the result without installing +# MathJax. However, it is strongly recommended to install a local copy of +# MathJax from https://www.mathjax.org before deployment. +# The default value is: https://cdn.jsdelivr.net/npm/mathjax@2. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_RELPATH = https://cdn.jsdelivr.net/npm/mathjax@2 + +# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax +# extension names that should be enabled during MathJax rendering. For example +# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_EXTENSIONS = + +# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces +# of code that will be used on startup of the MathJax code. See the MathJax site +# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an +# example see the documentation. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_CODEFILE = + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box for +# the HTML output. The underlying search engine uses javascript and DHTML and +# should work on any modern browser. Note that when using HTML help +# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) +# there is already a search function so this one should typically be disabled. +# For large projects the javascript based search engine can be slow, then +# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to +# search using the keyboard; to jump to the search box use + S +# (what the is depends on the OS and browser, but it is typically +# , /