Download and parse map data
###################################

Download OpenStreetMap data
*****************************************************

You can use the following two methods to download the OpenStreetMap
data:

1. `OpenStreetMapOfficial <https://www.openstreetmap.org/>`_:
choose ``Export`` -> ``OverpassAPI``
(otherwise the size of the bounding box size is limited).

.. image:: ../_static/map_related/osm_official.png
    :width: 100%
    :align: center
    :alt: OpenStreetMap Official

By this way, you will get the *complete* OSM data (xml),
then you can use ``osm_filter.osm_way_filter()`` to get
the layer you need.

2. `Overpass API <http://overpass-turbo.eu/>`_ (recommended):
directly use overpass API to download the layer you need.
The sample query code is attached in the appendix :ref:`query_code`.

.. image:: ../_static/map_related/overpass.png
    :width: 100%
    :align: center
    :alt: Overpass API

In this way, you will directly get the layer you need.


Parse OpenStreetMap data
*****************************************************

The downloaded OpenStreetMap xml file can be parsed using
the :func:`mtldp.mtlmap.build_network_from_xml`:

.. code-block:: python
    :linenos:

    import mtldp.mtlmap as mtlmap
    network = mtlmap.build_network_from_xml("*.osm")

This will return you a well-structured class
:class:`mtldp.mtlmap.Network`.



.. _query_code:

Appendix A: Query code
************************************************

Here is an example of the query code using the OverpassAPI.

.. literalinclude:: ../_static/overpass.xml
    :linenos:

.. _OpenStreetMapOfficial <https://www.openstreetmap.org/>:

Appendix B: Network classes
**********************************************

Network
=====================================

:class:`mtldp.mtlmap.Network` is the highest level
class that includes all different kinds of information of links,
segments, lane sets, and nodes defined blow.

.. image:: ../_static/map_related/network.png
    :width: 100%
    :align: center
    :alt: Network

Node
===========

Node is parsed from the ``node`` in the OpenStreetMap data.
Established based on a general :class:`mtldp.mtlmap.Node` class that
contains essential attributes including node id, GPS coordinates,
we further divide the nodes into different categories including
:class:`mtldp.mtlmap.SegmentConnectionNode`, :class:`mtldp.mtlmap.SignalizedNode`,
:class:`mtldp.mtlmap.UnSignalizedNode`, and :class:`mtldp.mtlmap.EndNode`.
In the figure below, the red mark denotes a signalized node.

.. image:: ../_static/map_related/node.png
    :width: 60%
    :align: center
    :alt: Node

Link
=========

:class:`mtldp.mtlmap.Link` is defined as a road segment composed of a series of segments that
connects two **signalized nodes**, and it includes direction information.
The blue arrows in the figure below denote the links between
two nodes.

.. note:: All the road segments including ``Link``, ``Segment``, ``LaneSet`` are directed.

.. image:: ../_static/map_related/link.png
    :width: 60%
    :align: center
    :alt: Link

Segment
===========

:class:`mtldp.mtlmap.Segment` is used to define a road segment that has the uniform
tags and parameters (speed limit, lane number and usage, etc.). Each segment is directly
generated from a ``way`` from the OpenStreetMap data (we also have a
class :class:`mtldp.mtlmap.OsmWay` that is directly parsed from the OpenStreetMap data).
In the figure below, the blue arrows
denote the segments. There might be multiple segments between
two nodes.

.. image:: ../_static/map_related/segment.png
    :width: 60%
    :align: center
    :alt: Segment

LaneSet
====================

:class:`mtldp.mtlmap.LaneSet` class denotes a set of lanes that has the same downstream direction
(e.g. through, right turn, left turn).
The blue arrows in the figure below denote the lane sets.
For example, the blue arrows that are connected to the left
intersection represent the through movement and left turn
movement.

.. image:: ../_static/map_related/laneset.png
    :width: 60%
    :align: center
    :alt: LaneSet