Appendix

OSM Data in a PostGIS Database [Builder]

The following chapters are dedicated to give some information and pointers to keeping OSM data in a database instead of files for processing in osm2city. This is not a complete guide and will concentrate on only one possible scenario: PostGIS on Ubuntu Linux.

Some overall pointers:

Developer Information

Documentation

You need to install Sphinx. All documentation is written using reStructuredText and then made available on Read the Docs.

Change into docs/manual and then run the following command to test on your local machine:

$ sphinx-build -b html . build

Developing

An unstructured list of stuff you might need to know as a developer:

  • The code has evolved over time by contributions from persons, who are not necessarily professional Python developers. Whenever you touch or even only read a piece of code, please leave the place in a better state by adding comments with your understanding, refactoring etc.
  • The level of unit testing is minimal and below what is achievable. There is no system testing. All system testing is done in a visual way - one of the reasons being that the scenery generation has randomising elements plus parametrisation, which means there is not deterministic right solution even from a regression point of view.
  • Apart from testing the results in FlightGear by flying around with e.g. the UFO, a few operations make use of a parameter DEBUG_PLOT_*, which plots results to a pdf-file:
    • DEBUG_PLOT_RECTIFY: Examples of rectified building floor plans
    • DEBUG_PLOT_GENBUILDINGS: Result of generating buildings
    • DEBUG_PLOT_LANDUSE: Different aspects of land-use
    • DEBUG_PLOT_ROADS: Different plots for aspects of roads processing
    • DEBUG_PLOT_OFFSETS: Showing offsets when placing rectangle (utility function)
  • Use an editor, which supports PEP 08. However the current main developer prefers a line length of 120 instead. You should be able to live with that.
  • Use Python type hints as far as possible — and help improve the current situation. It might make the code a bit harder to read, but it gets so much easier to understand.
  • Try to stick to the Python version as referenced in requirements.txt (cf. Python).
  • All code in utf-8. On Windows please make sure that line endings get correct in git (core.autocrlf)
  • Coordinate systems:
    • FlightGear uses a set of different coordinate systems. The most important for referencing models in stg-files is WGS84, which uses lon/lat. In the Cartesian coordinate system in a tile +X is North, +Y is East and +Z is up.
    • OSM references WGS84 as the datum.
    • The Ac3D format uses x-axis to the right, y-axis upwards and z-axis forward, meaning that the bottom of an object is in x-z space and the front is in x-y. I.e. a right-handed coordinate system.
    • osm2city uses a local cartesian coordinate system in meters close enough for measurements within a tile, where x is lon-direction and y is lat-direction. The object height is then in z-direction (see module utils/coordinates.py). I.e. x pointing to the right and y pointing inwards in a right-handed coordinate system. Meaning the bottom of an object i in x-y space. Therefore a node in the local (cartographic) coordinate system gets translated as follows to a node in a AC3D object in osm2city: x_ac3d = - y_local, y_ac3d = height_above_ground, z_ac3d = - x_local