Quick Start¶

Welcome to Merkaartor. Glad you made it here. After starting the application the first time you can move the background map around by holding the right mouse button and dragging (or using the arrow keys).

Zoom the map with the mouse wheel (or the + and - keys, or F3 and selecting an area) and go to an area that you'd like to edit.

If you don't see a background map, choose one in the context menu of the Map layer in the Layers dock. Once you're there, select "Download from web" from the "File" menu.
In the Download dialog, make sure the "Current view" option is selected, then hit OK. Now Merkaartor connects to the OpenStreetMap server and requests all map data for the select area. If the area was too big, the server might refuse to send data. Zoom in a little more and try again. If you later want to load additional data from OSM, the menu command "File, Download more" will take care of this.

The downloaded data in the "Download" layer is drawn over the background map. Areas that have not been downloaded from OSM are marked with a red dots pattern – don't edit there, but download OSM data first!

If you select a node or a way, the "Properties" dock will show all its tags. If you want to learn more about those tags, look at the Map Features wiki page. For example if you know of a post-box or a restaurant that is missing on the map, use the menu command "Create, Node" to put it on the map and then add the necessary tags. Merkaartor simplifies this with the "Amenity" dropdown menu from the Properties layer. It offers a selection of predefined tag sets that describe common things.

A recorded GPS track file can be imported to a new layer with "File, Import". Before you add a new way based on your track, make sure that you've downloaded the current OSM data, then use "Create, Road" to draw the way.

Unlike when using Potlatch, the online map editor, changes made in Merkaartor have to be deliberately uploaded to the server. To do this, use the menu command "File, Upload". Therefore, you need to specify your OSM account in the preferences window. (You'll have to fill in this information before the menu item is enabled.)

Look here for a quick walk through or the manual.

Installation¶

Linux, Mac OS X¶

There are several binary packages available for diverse Linux distributions. See the [http://www.merkaartor.org/Download/ Merkaartor download page] for details. You can also compile Merkaartor from source code.

Requirements¶

Merkaartor requires Trolltech '''Qt''' version '''4.3.3''' or greater (source available at http://trolltech.com/downloads/opensource, packages are probably available for every single Linux distribution.)

Optional packages¶

PROJ4 is highly recommended, for top-of-notch projection management
GDAL is also highly recommended. It allows to handle GeoTIFFs and a ton of other GIS formats
exiv2 is required for geo-tagged images
gpsd is required to access a gps through the gpsd daemon
zbar (version >= 0.10) is required for automatic recognition of walking paper scans localisation
libproxy is used for improved proxy detection on linux and Mac

Windows¶

You can download a Windows installation package from the Merkaartor download page.

There is a separate how-to about building Merkaartor from source with Qt and MinGW on Windows. This covers all requirements and optional libraries. Windows binaries of the optional DLLs are included in the Windows installation package.

Main Window¶

The Map¶

Interactions with the map¶

Keys:

arrows: pan viewport
+,-: zoom in/out

Mouse:

button 1: see table below; actions depend on whether "Single mouse button interaction" is set in preferences.
button 3: click for context menu; drag to pan; control-drag to zoom to area
wheel: zoom in/out

{| border="1" |+ Mouse actions button 1
! Function !! Multi-button !! Single-button |- || Select feature || click || click |- || Add feature to selection || shift+click || shift+click |- || Toggle feature's selection || control+click || control+click |- || Remove feature from selection || - || - |- || Select features within rectangle || drag || shift+drag |- || Select features intersecting rectangle || shift+drag (1) || alt+shift+drag (1) |- || Deselect or toggle features within rectangle || - || - |- || Deselect features outside rectangle (intersection operator) || - || - |- || Move feature (unless Separate Move Mode set) || drag feature || drag feature |}
Note (1) - if shift is pressed when mouse button is '''released'''.

The Docks¶

Many details about the current editing session can be found in the docks. These widgets can be freely placed left and right of the main map or as separate windows. Accidentally closed docks can be opened again in the menu "Window, Docks, ...".

Layers dock¶

The various data sources like a background map, the GPS tracks, data downloaded from the OSM server or data yet to be uploaded to the server are shown in the Layers dock. It is possible to show/hide specific layers by left clicking on
the little eye widget next to each layer's name.

A right mouse click on a layer item opens the context menu. Here you can select the opacity of each layer and zoom the visible area of the map to the bounding box of a layer's content.

The map layer is special in that it describes what is drawn in the background.
You can upload in background Geotiff or GdalRaster picture, and there are various servers to choose from, for example the Mapnik tile server or the tiles@home server. If your build of Merkaartor has Webkit support, Yahoo aerial images are available, too.

The download layer shows what has been retrieved from the server, while the dirty layer holds the edits that have not been uploaded to the OpenStreetMap server yet.

Geo Images¶

[[Image:merkaartor-geo-image.png|400px|right|thumb|sample of Geo Image dock]]

The Geo Images dock is only available if explicitly compiled with this feature. It's being used to view geotagged images.

At least one track layer needs to be open (File - Import). After that, geotagged images can be opened using CTRL+o or through the menu. For each image, a small rectangle will appear on the map. By selecting the image icon (rectangle) the image will be shown in the Geo Images dock. Now you can start editing the map with all the relevant details you can derive from that image.

Use the mouse wheel to zoom the image or double-click it (hold CTRL to zoom out). If zoomed, you can click and hold the image to move it.

To select the next/previous image, press PAGE DOWN/UP respectively.

File¶

New

Open

Import

Recent open

Recent import

Export

Render

Native
: Allow the creation of a bitmap using the builtin, stylized, render engine.
Osmarender
: Allow the creation of a SVG representation of the data, using Osmarender. Optionally, allow to create a bitmap from the SVG (requires [http://www.inkscape.org/ Inkscape])

Save

Save as

Download

Download more

Upload

Work Offline

Quit

Edit¶

View¶

Gps¶

Layers¶

Create¶

Feature¶

Node¶

Road¶

Relation¶

Tools¶

Style

Tag templates

Shortcut Editor...

TMS Servers Editor...

WMS Servers Editor...

The WMS Servers Editor allow you to add WMS servers to the list of WMS servers available as background images.

WMS-C Servers

[[Image:Merkaartor_wmsc_setup.jpg|320px|right]]

Merkaartor support WMS-C servers as specified by the [http://wiki.osgeo.org/wiki/WMS_Tiling_Client_Recommendation OSGeo recommendation].

More specifically, Merkaartor's implementation is based upon [http://labs.metacarta.com/ Metacarta Labs] implementation of the recommendation in its [http://tilecache.org/ TileCache] product.

Basically, WMS-C defines a way to allow caching of WMS requests by offering a tiling interface (à la slippy map) to WMS servers, whose capability to provide images of arbitrary sizes and bounding boxes make them hard to cache.

When adding a server that support WMS-C, Merkaartor will detect this and inform the user, hiding un-relevant WMS information. The user can then just select the desired layer and click <Apply> (or <Add> if it is a brand new server).

Reset Discardable dialogs status

Preference...

Window¶

Help

Editing the map¶

Moving a node¶

Depending on the preference setting "Separate Move mode", you either have a designated Move tool available or can move a node after selecting it. With the Move tool, you can move any node by dragging it in the map. With the Select tool, you first need to click on it once to select it, then you can drag this node in the map. Selecting it first avoids accidential moving.

Creating a new node¶

Use the menu command "Create, Node" and click on the location of the map where the new node shall be created. The new node appears as a question mark icon. To set tags for the new node, use the Select tool and click on the new node to select it. ''(From 0.14 on the new node is automatically selected.)''

You can insert a new node into an existing way to give it a smoother path or to otherwise add a detail to it. Again, use the menu command "Create, Node" and put the mouse cursor on the location where the new node shall be inserted. When hovering an existing way segment, it is highlighted. Now you can click on the path to insert the node into that way. The new node is automatically inserted into the way and moving the node around will also modify the way path.

To explicitly not insert the new node in an existing road near where you want to create the node, press and hold the Ctrl and Alt keys to prevent snapping to roads.

Creating a new way¶

Be sure not to have a node selected before you start creating a way. Use the menu command "Create, Road" and click on the location of the map where the first node of the new way shall be created. Then move the mouse cursor to the location where the second node shall be created. While moving the cursor, a preview line shows the path of the new way segment, along with the distance to the last created node. After adding the last node, press the Escape key or select the Select tool. The new way appears as a thin black line. To set tags for the new way, use the Select tool and click on the new way (not one of its nodes) to select it. ''(From 0.14 on the new way is automatically selected.)''

If you hover the mouse cursor over an existing road or node, it will snap to that road/node. This way you can start or end a new road at an existing node or in the middle of an existing road. Please do so whenever there shall be a connection between the existing object and the new road, e.g. at road junctions.

To explicitly not insert a node of the new road in an existing road near where you want to create the node, press and hold the Ctrl and Alt keys to prevent snapping to roads. This is useful for creating roads nearby areas when both objects have no direct connection.

Creating a new area¶

There are multiple ways to create a new area. You can for example create a predetermined shape by choosing "Rectangle" or "Polygon" from the "Create"-menu. Clicking the first time in the working area will start the shape, clicking the second time finishes the shape. You can now add key:value-combinations to clarify its use.

Usually though your areas will need to be more free-form. In this case it is more convenient to choose "Area" from the "Create"-menu, or simply click the button "Area" in the main toolbar. You complete the area by clicking for the second time on the first node you put down. A menu will pop-up asking if you want to add a(nother) hole to this area, which you usually won't.
Now that you're done putting down the area, a very convenient tool is to align the axis by choosing "Axis Align" from the "Road"-menu. If all your corners are at a 90 degree angle, choosing 4 will ensure they are exactly 90 degrees in your created area.
Don't forget to add some key:value to clarify its use.

Continuing an existing way at either end¶

Use the Select tool to select the node at the end of the way you want to continue. Then use the menu command "Create, Road" and continue to create the way as described above in ''Creating a new way''.

The selected node will automatically be the first node of the way segment you're drawing. If the node was at the end of a single road, the road will be expanded by the new nodes you draw. If the selected node was in the middle of a road, or the end of more than road, a new road will be created.

Removing a node/way¶

Removing a node makes it entirely go away! You can use this to remove single nodes or nodes from a way. Be sure that you won't accidently delete a special map feature from a way node. Use the Select tool to select the node (not the way) you want to delete. Then click on the red Remove toolbutton to remove that node.

Removing a way works the same, only that you select the entire way instead of a single node on it.

Splitting a road¶

Splitting a road is a common task to get a road split up into two segments and assign them different tags, like road names or maximum speeds. Use the Select tool to select the road you want to split. Then hold the Shift key pressed and select the node on the road at which the road shall be split. Then use the menu command "Road, Split" to split the road. You can now use the Select tool to further edit both segments of the road separately.

In simple cases, it may be sufficient to only select the node (not the road it is on) and use the menu command.

You can select multiple nodes on the selected road to split the road into more than two parts in one step. You can use this for example to be able to tag a small part of a road separately, like a bridge or a short speed limit.

Splitting a road does not mean disconnecting the two parts. Splitting a road allows you to assign different tags to each part. ''Read below on how to disconnect (break apart) connected roads to independently move their endpoints.''

Break apart connected roads¶

Connected roads usually share a single node at their connecting ends. Moving the end of one road also moves the end of the other road, because they're connected. To break up both roads, use the Select tool to the roads that you want to break apart. Then use the menu command "Road, Break apart" to duplicate the connecting node and thus disconnect the roads. (All tags assigned to the node are also duplicated.) You can now use the Move tool to move each road ends independently.

Since both nodes lie at the very same position, you can only select one node at first. See ''Moving a node'' above about how to select the right node to move.

Breaking apart two roads that are still connected to a third road will always disconnect the two roads that you have selected, but may keep other combinations of connected roads glued together. To break apart all roads that connect in a node, select all ways that go through this node.

Joining two roads¶

Roads may be added to the map in several steps. If you have extended a road by creating a new way starting or ending at another road's endpoint, you basically have two connected but separate roads. Separated roads are harder to maintain because features must be added or changed to more ways. If both roads shall have the same tags, use the Select tool to select both roads to join. Then use the menu command "Road, Join" to combine both ways into a single way.

Should both roads have set different values for common tags, their values are concatenated in the joined road. The combined road has all tags assigned that either road had assigned before, i.e. the tag set is united.

You cannot join roads that are not connected in a common endpoint, i.e. you cannot combine roads connected in a junction or crossing.

Read above on how to split a road at a given node.

Detaching a node from a way¶

Detaching a node from a way, you can move it around without altering the way it was part of. This can also help to correct situations when you have moved a node too near to a way so that it has become a part of the way. Use the Select tool to select the node you want to detach from a way. Then use the menu command "Node, Detach" to detach the node from the way. You can now use the Move tool to further move the node somewhere else.

This feature is available from version 0.14 on.

Editing tags of an object¶

To edit the tags of an object (node, way or relation), select the object and add or change the tags in the "Properties" dock. You can edit a tag name or value by either clicking once on the table cell and start typing, or first double-click the table cell to get a text input field (if your first typing character would be an application hotkey). To add a new tag, select the last row of that table. To delete a tag/value pair from the selected object(s), select it in the table and click on the delete button right above the tags table (the one with the red X on it).

Keyboard Shortcuts¶

Listing only the most important shortcuts which help during the editing process

ESC Switch to "Select" mode
DEL Delete selected object
Ctrl-M Switch to "Move object" mode
Ctrl-N Switch to "Create Nodes" mode
Ctrl-R Switch to "Create Streets" mode
Ctrl-D Download OSM data
Shift-Ctrl-D Download OSM data for current viewport
Ctrl-U Upload your changes to OSM

Roads¶

Alt-S Split: Select a road-node where to split. The result is two roads which are still connected by the one node.
Alt-B Break apart: Select two connected roads (connected by one node) and they will become separated (two nodes).
Alt-J Join: Select 2 streets to combine them. Attributes (keys) will be preserved. Conflicting attributes are concatenated with ";".

Nodes¶

Alt-M Merge: Select 2 or more nodes and they become one. Handy for resolving "nodes on the same spot" errors.
Alt-A Align: Move nodes onto line defined by first and second in selection

Selection¶

TAB: After selecting node-road, press Tab to cycle through the nearby/overlapping elements

Relations¶

Downloading a relation¶

If a relation is partly downloaded (red dashed border), the rest of its members can be fetched as follows:

Select the relation in the Features dock
Right-click it and select "Download missing children"
The border of the relation will turn green to indicate that it is fully downloaded

Adding to a relation¶

'''NOTE''': this needs a Merkaartor newer than version 0.13.

Select the relation to add a member to. To do so, click on the dashed bounding box around a relation. For more clarity, you can enable "View" - "Show Relations"
Ctrl-click the feature (road or other) to add to the relation
Select "Relation" - "Add Member"

Tag Selectors, Styles and Tag Templates¶

Tag Selectors is the syntax by which one can define on which features the styles, tag templates, ... applies.
Styles change the way Merkaartor renders the map, and allow users to change colours, line thicknesses, etc.
Tag Templates define easier ways to enter tags, ensuring that users follow the OSM standards, and making editing quicker.

Troubleshooting¶

If you have any problems with Merkaartor or think that something went wrong, this section may or may not have the answer for you.

Yahoo imagery offset¶

If the Yahoo background image is offset by a fair amount (about 240 pixels on the screen in all zoom levels) or the map tiles won't fit together after zooming, use the menu command "Layers, Map - Yahoo, Yahoo adapter" to align the background image correctly again. This always seems to happen when you start Merkaartor with the Yahoo Map layer disabled and then enable it after downloading some OSM data.

Should the Map item be missing in the Layers menu, you can also use the context menu on the Map layer from the Layers dock.

If the imagery is only a few metres off, that's by design and cannot easily be corrected.

Property window keeps growing¶

Every time one clicks into the main window the property window size increases both horizontally and vertically. It's not possible to make the window smaller by moving the divider. This makes it impossible to use the program after a while.

Solution: This a Qt issue, solved in 4.5.1. Select a custom Qt style like skulpture or cleanlooks in Preference-visual.

Adding Additional Projections¶

When you install Merkaartor, it includes support for two spatial reference systems: Lat/Long (epsg:4326) and World Mercator (epsg:3785). It is pretty easy to add support for additional spatial reference systems. The most common case for wanting to do this is when there are Web Map Services (WMS) that can be used for tracing/editing, but those services do not support one of the two default spatial reference systems.

To add support for a new spatial reference system, you just need to add a definition for that projection to the file that stores this information. Here are the steps:

Merkaartor projections are stored in Proj.4 format. An easy way to get the definition for your spatial reference system(SRS) in the correct format is to go to [http://spatialreference.org/ spatialreference.org] and search for it. Once you locate the correct SRS, click the link that will give you the SRS definition in Proj.4 format. Here is a link to [http://spatialreference.org/ref/epsg/26915/proj4/ UTM Zone15N NAD83]
Projections are stored in a file called Projections.xml. This file is located in a hidden folder called merkaartor in the user's home directory. On Mac OS X or Linux, the path is ~/.merkaartor/Projections.xml. On Windows, it is at HOMEDRIVE%HOMEPATH%\.merkaartor (e.g. c:\Users\MyUser\.merkaartor). ''Note the dot character at the beginning of the folder name, it indicates that the folder is hidden.''
Find this file and make a backup. Open Projections.xml with your favorite text editor. Copy one of the other Projection elements and paste in the Proj.4 definition that you got from spatialreference.org. Here is a new entry for UTM Zone15N: <nowiki><Projection name="UTM 15N NAD83 (epsg:26915)" >+proj=utm +zone=15 +ellps=GRS80 +datum=NAD83 +units=m +no_defs </Projection></nowiki>.
Start up Merkaartor and go to View>Set Projection. You should see your new SRS listed there.

This is the full file after edition:
<source lang=xml highlight="6">

<MerkaartorList>
<Projections creator="Merkaartor 0.14" >
<Projection name="Mercator (epsg:3785)" >+proj=merc +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0 +ellps=WGS84 +datum=WGS84 +no_defs</Projection>
<Projection name="EPSG:4326" >+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs +to_meter=0.017453292519943295769236907684886</Projection>
<Projection name="UTM 15N NAD83 (epsg:26915)" >+proj=utm +zone=15 +ellps=GRS80 +datum=NAD83 +units=m +no_defs </Projection>
</Projections>
</MerkaartorList>
</source>

Merkaartor

Wiki