.. _chapter-appendix-label: ######## Appendix ######## .. _chapter-osm-database-label: ======================================== 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: * PostGIS on OSM wiki: http://wiki.openstreetmap.org/wiki/PostGIS * Book PostGIS in Action, especially chapter 4.4 of the 2nd edition: http://www.postgis.us/ * PostgreSQL on Ubuntu: https://help.ubuntu.com/community/PostgreSQL * Volker Schatz's online manual of OSM tools: http://www.volkerschatz.com/net/osm/osmman.html, e.g. osm2pgsql `database format `_ and `usage `_. * HStore information in PostgreSQL: https://www.postgresql.org/docs/devel/static/hstore.html * HStore and minutely OSM planet dump info in German: http://wiki.openstreetmap.org/wiki/DE:HowTo_minutely_hstore ===================== 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 .. _Sphinx: http://www.sphinx-doc.org .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _Read the Docs: https://readthedocs.org/ ---------- 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. :ref:`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 .. _UFO: http://wiki.flightgear.org/UFO_from_the_%27White_Project%27_of_the_UNESCO .. _PEP 08: https://www.python.org/dev/peps/pep-0008/ .. _type hints: https://docs.python.org/3/library/typing.html .. _coordinate systems: http://wiki.flightgear.org/Geographic_Coordinate_Systems .. _WGS84: https://en.wikipedia.org/wiki/World_Geodetic_System