maposmatic/documentation/user-guide.adoc

MapOSMatic User Guide
=====================
Hartmut Holzgraefe <hartmut@php.net>
:toc:
v0.1, May 5th, 2018
Work in progress

:imagesdir: ./img
:data-uri:
:numbered:

Overview
--------



Creating a map - step by step
-----------------------------

The map creation form leads you through a series of steps that each
cover a specific step in the overal map creation workflow. Which
step you are in is visualized in an icon bullet bar.

image::step-progress-bar.png[Step progress bar,width=80%,pdfwidth=80%,align=center]

You can only navigate between steps with the [Next] and [Back] buttons
though, as some steps depend on spefic input from previous steps.
So it is not possible to navigate between arbitrary steps by clicking
on the step icons.

The [Next] button will appear whenever a valid choice was made in
the current step, the [Back] button is visible on all but the first
step. On the final step a [Generate Map] button is shown instead
of the [Next] button.


Select a map area or upload a file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

At the very beginning the map area to be rendered needs to be determined.
For this there are currently three alternatives, available as different
form tabs:

* Directly select a rectangular area on an online map.
* Use a city or place name to look up its boundaries in the OSM database.
* Upload a GPX track, Umap export, or GeoJSON file. The map area will be determined by the contained data.

When uploading files you can still select a different, e.g. smaller or larger,
map area afterwards.



Directly Select Area
^^^^^^^^^^^^^^^^^^^^

image::select-area.png[Select Area,width=80%,pdfwidth=80%,align=center]

Here you can select a rectangular map area. The map shown is a typical “slippy” online map,
on the left you have buttons for zooming in and out, a button to detect your current location,
and a search button to search for a place by name.

By default the full visible map area is selected here, but you may also use the *[Select area]*
button to enable a more sophisticated area selection tool.

When pressing the *[Select area]* button the user interface changes a bit, you'll now see a
highlighted rectangular area that marks the actual selected area. You can drag the four corners
of the rectangle around to change its shape and size, and you can move the complete area by
dragging it along by the dotted marker in its upper left corner.

With *[Select area within current zoom]* you can make the full visible area the new selection,
and the *[Remove selection]* brings you back to the original mode.

The four number fields below the map show the current min. and max. latitude and longitude
of your selected area.

When you are satisfied with your selection you can use the *[>]* button on the right to move
on to the next form step. 



City Search
^^^^^^^^^^^

image::select-city.png[Select City,width=80%,pdfwidth=80%,align=center]

On the “City search” tab you can enter a city or place name in the input field, if the administrative
borders of that city or place are known to OpenStreetMap these can be used to determine the map area
to use automatically.

A dropdown below the field will show possible matches for your input as you type. Only the matches
that are printed in black are selectable. The matches printed in grey are either place nodes for
which no border information is available in OSM yet, or the place area is too large to be printed
with this web service. 


Upload data files
^^^^^^^^^^^^^^^^^^

image::step-upload.png[File Upload,width=80%,pdfwidth=80%,align=center]

Here you can upload data files containing geographic featuers in the form
of GPX tracks, http://umap.openstreetmap.fr[Umap] exports, or general
GeoJSON files, which will then be rendered on top of the base map.

The upload form performs some basic checks, so it will complain when one of
the uploaded files is not in a supported format, or does not contain any
actual data.

Note that the files will be stored on the web server, and that the map generated
from them (but not the actual uploaded files themselves) will be visible to 
everyone. So do not upload any sensitive data you don't want to to be seen in 
public, or that you don't have the permission to share in public.

Once files have been selected and verified, the form switches back to the
area selection tabl, where it will show a preview of the imported file
contents, and the optimal map area to display all contained data.

image::gpx-selected.png[GPX Preview,width=80%,pdfwidth=80%,align=center]

If you want to render a different area, e.g. just a smaller part of the data, 
or a larger area showing more context beyond the data itself, you can change the
selection area accordingly.

Uploading a GPX track
+++++++++++++++++++++

When uploading a GPX track the contained track, and any named way points
will be rendered on top of the base map.

The actual final result of e.g. a rendered GPX track may look like the example below:

image::gpx-result.png[GPX Render Result,width=80%,pdfwidth=80%,align=center]


Uploading a Umap File
+++++++++++++++++++++

You can upload a file exported from Umap, a service that lets you create online
maps with your own markers and drawings on top. We provide you with a way to also use
this fine tool to produce customized printed maps with your own data on top, and not
only online maps.

To create an export file from a Umap you created you need to click on the
“Embed and Share” Icon on the left side of the Umap interface, and then use
“Download Data → Full map data” in the sidebar on the right hand size.

Only data directly added using the Umap drawing tools will be rendered for now.
Umap also allows to import external data on the fly, like data form CSV files,
or dynamic queries against an Overpass API Server, this kind of data is not
supported by this service yet though, and so will not be part of the generated
print map.

image::umap-selected.png[Umap Preview,width=80%,pdfwidth=80%,align=center]

Like with GPX uploads, once a valid Umap file has been selected for upload the form
will switch back to the area selection tab and will show a simplified preview of the
uploaded data.

You can modify the selected area if you only want to show part of the Umap
information, or actually want to show it in a larger map context.

image:umap-result.png[Umap Render Result,width=45%,pdfwidth=45%]
image:umap-actual.png[Umap Original Online Map,width=45%,pdfwidth=45%]

An actually rendered Umap map may look like the example on the left hand side above,
while the right hand side shows how the original online Umap looks like.
The results are not completely the same , especially when it comes to line stroke
width, but this is mostly due to difference in size an resolution of the target
devices, paper vs. screen. 



Select a paper layout
~~~~~~~~~~~~~~~~~~~~~

In this step you can choose between different paper layouts.

image::step-layout.png[Paper Layout,width=80%,pdfwidth=80%,align=center]

There are four different single page layouts, and one for multi page
booklets.

The basic single page layout uses the full page for the map.

The next two single page layouts add a street index to the
map, either on the side -- left side for left-to-write languages,
or right side for right-to-left languages like Arabic or Hebrew --
or at the bottom.

The fourth single page layout renders a full page map, like the
basic layout, and puts the street index on a second page in the
generated PDF. The other generated formats will not contain an
index as they do not support multi page output.

The multi page layout creates a multi page booklet with a title
page, an overview page, a collection of detail map pages, and
a street index.

The preview on the right hand side changes with your selection,
it does not show the actual selected map area though. It is
just using pre-rendered examples to give you a rough idea
what each layout looks like.

For all but the "Full-page layout without index" layout the actual
index generator can be selected. The default selection "Streets and
selected amenities" generates a classic street index, but there are
also a few "special interest" alternatives available.

Right now these are:

* Healt related facitilies - a work-in-progress index of health facilities and districts
* OSM notes index - an experimental indexshowing current OSM notes for the selected area 
* Tree genus / species index - showing what kinds of different trees are growing in an area, most useful for small areays like allotment colonies

Select a map style
~~~~~~~~~~~~~~~~~~

Here you can select the style of the base map.

image::step-style.png[Map Style,width=80%,pdfwidth=80%,align=center]

Style selections are grouped by specific themes, e.g. for
country specific styles. Only one base style can be selected.

The preview on the right hand side again changes with your
selection, and only shows a fixed pre-defined map area,
not the area you actually chose, to give you a quick
rough idea what the chosen style looks lie.

Optionally: Select map overlays
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Map overlays are rendered on top of the basemap. They can
either add decoration elements like a compas rose or scale
bar, or additional special interest map features like
hiking routes, fire hydrants or height contour lines.

image::step-overlay.png[Map Overlays,width=80%,pdfwidth=80%,align=center]

Overlay styles are also grouped by theme like the base styles,
but here you can select multiple overlay styles, not just one.

The preview on the right only shows the last overlay you
selected, on top of the Black&White base style for better visibility
of the overlay additions, not a combination of all selected overlays.


Select paper size an orientation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In this step the minimal required paper size is calculated,
and you are given a choice of predefined paper formats that
are larger than this, plus a "best fit" option. You can select
one of the suggested paper sizes, or enter a custom width and
height that suits your needs yourself.

image::step-papersize.png[Paper size selection,width=80%,pdfwidth=80%,align=center]

For paper sizes large enough for the selected map area the
respective buttons are shown in blue, or in green for the
actual selected size. If a paper size is too small for the
given area the corresponding button is only shown in gray.

The left sie of the form will show a rough preview of the
chosen size and orientation, showing width and height and
a visual representation that will give you an idea of the
aspect ration. The preview also contains a rough scale
estimate, and the zoom factor the map will be redered with.


Select map title and locale
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is the final step before submiting the rendering job.
Here you can select a map title, the language for map
annotations, and optionally give your email address if
you want to be informed via mail when your request has
been processed.

Also a quick summary of your choices is shown.

image::step-submit.png[Final steps,width=80%,pdfwidth=80%,align=center]

The map title is prefilled if you used the city selection
to specify the map area. If you uploaded GPX or Umap
files the map title will also be prefilled if title information
was found in the uploaded files.

The chosen locale is used for the annotations and copyright
information at the bottom of the map, and for section titles
in the street index. In the German style it also influences
the language choice for actual map features, the other styles
still use a fixed language setting so far though. In the fire
hydrant overlay the hydrant symbols can be locale specific,
right now this is only implemented for the Austrian "de_AT"
locale.

If you provide an email address you will be notified when
your rendering request has been processed successfully, or
ran into an error. The email address entered here will
only be stored for 48 hours, and will usually only be used
to send the result notification. In case of rendering errors
you may also receive feedback questions to help debugging
the problem, and in case of a bug fixed you will be informed
about a successful re-rendering of your request.


Map styles
----------

Default styles
~~~~~~~~~~~~~~

CartoOSM
^^^^^^^^

This is the default OpenStreetMap style, as used on http://osm.org/[the OpenStreetMap Website].

The installed style sheet is usually up to date with the latest released version of the style,
in the future it may also be possible to select older versions of the style.

TODO: image


MapOSMatic printable
^^^^^^^^^^^^^^^^^^^^

This style was originally developed along with the MapOSMatic web frontend and renderer,
to provide a style more suitable for printed output than the original OpenStreetMap Carto
style. Unfortunately it is basically unmaintained and has not seen any updates in several
years now.



Black&White styles
~~~~~~~~~~~~~~~~~~

CartoOSM B&W
^^^^^^^^^^^^

This is a variant of the CartoOSM style in which all color values have been replaced
with equivalent grayscale values. This style variant is suitable for printing on
single color printers, and as a underlying base style when using one of the map
overlay styles, so that the overlay featuers clearly stand out.


Stamen Toner
^^^^^^^^^^^^

The Toner style, originally created by Stamen Design, uses clear black and white
only, and so produces a very high contrast result.


Country specific styles
~~~~~~~~~~~~~~~~~~~~~~~

German
^^^^^^

The German style is a fork of the CartoOSM style, with some features styled a bit
differently to closer match typical German map design. For example the color scheme
for major roads is different to the original OSM style.

The German style also supports localization, so with this style the locale choice
in the final form step not only affects the language the copyright notices and
annotations at the bottom of the map are printed in, but also the language used
for labels on actual map features.

French
^^^^^^

Belgian
^^^^^^^

Swiss
^^^^^

Sports
~~~~~~

Hike&Bike map
^^^^^^^^^^^^^

OpenRiverBoat
^^^^^^^^^^^^^

PisteMap
^^^^^^^^

Veloroad
^^^^^^^^

Artistic
~~~~~~~~

Pencil style
^^^^^^^^^^^^

Space station
^^^^^^^^^^^^^

MapQuest styles
~~~~~~~~~~~~~~~

Europe
^^^^^^

UK
^^

USA
^^^

Hybrid variants
^^^^^^^^^^^^^^^

Special interest
~~~~~~~~~~~~~~~~

HOT Humanitarian style
^^^^^^^^^^^^^^^^^^^^^^

OpenTopoMap
^^^^^^^^^^^

Low contrast
~~~~~~~~~~~~

OsmBright
^^^^^^^^^

Blossom
^^^^^^^

Pandonia
^^^^^^^^

Empty
^^^^^

The Empty style does not render anything at all. It was originally added as an aid for
overlay development, to be able to render maps contianing overlay features only.

In combination with the Schwarzplan overlay it now serves a valid non-debug purpose, too,
allowing to print pure Schwarzplan output.


Overlay styles
--------------

Overlay effects
~~~~~~~~~~~~~~~

The effects overlay add different kinds of decorations to the map.
They do not read and present actual map data.

Scale bar
^^^^^^^^^

The scale bar overlay gets placed in the lower left corner of
the map. It shows the real world size of the map grid squares,
and the actual map scale factor.

image:overlay-scalebar.png[Scalebar overlay,width=45%,pdfwidth=45%]


Compass rose
^^^^^^^^^^^^

The compas rose gets placed in the upper left corner of the
map and shows the direction of true geographic north. For
now it just points straight up as unfortunately the Mapnik
renderer does not support on-the-fly rotation of map data.

image:overlay-compass.png[Compass overlay,width=45%,pdfwidth=45%]



QR-Code
^^^^^^^

The QR code gets placed in the lower right corner of the
map. For now it only contains the URL of the map request
itself, allowing to re-create the same map with up-to-date
data.

In the future there will be a form field for custom text
input.

image:overlay-qrcode.png[QRcode overlay,width=45%,pdfwidth=45%]




Map data overlays
~~~~~~~~~~~~~~~~~

Contour lines
^^^^^^^^^^^^^

TODO ...


WayMarkedTrails routes
^^^^^^^^^^^^^^^^^^^^^^

TODO ...


Hiking
++++++

TODO ...


Cycling
+++++++

TODO ...


Mountain bike
+++++++++++++

TODO ...


Riding
++++++

TODO ...


Skating
+++++++

TODO ...


Slopes
++++++

TODO ...


Transport overlays
^^^^^^^^^^^^^^^^^^

Public transport map
++++++++++++++++++++

TODO ...


OpenRailwayMap
++++++++++++++

TODO ...


Special interest overlays
^^^^^^^^^^^^^^^^^^^^^^^^^

Fire hydrant overlay
++++++++++++++++++++

This overlay was inspired by http://openfiremap.org/[OpenfireMap].

It currently shows fire stations, fire hydrants and other emergency water
sources, emergency access points, and public defibrilators.

This overlay has limited map local support, using different
icons for hydrants by country.

So far it only has country specific icons for Switzerland, when
selecting "Schweiz (DE)" as map locale.

For all other locales the default OpenFireMap icon set will
be used.

image:overlay-fire.png[Fire hydrant overlay,width=45%,pdfwidth=45%]
image:overlay-fire-ch.png[Swiss hydrant overlay,width=45%,pdfwidth=45%]


Maxspeed overlay
++++++++++++++++

TODO ...


Surveillance cameras
++++++++++++++++++++

TODO ...


Schwarzplan overlay
+++++++++++++++++++

TODO ...


Gaslight overlay
++++++++++++++++

TODO ...