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.

Changes made in Merkaartor have to be deliberately uploaded to the server, to do this, use the menu command "File, Upload". If you haven't specified your OSM account in the preferences window the Upload command will prompt you to fill in this information.

Main Window

The Map

Interactions with the map

button 3: click for context menu; drag to pan; control-drag to zoom to area

wheel: zoom in/out

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. 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

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.

The Menu

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 Inkscape)

Save

Save as

Download

Download more

Download OpenStreetBugs

Download OpenStreetBugs for the current map view (if any). If any bugs exist, they will show as a small red square icon. The icon is so small that you may need to zoom in to see it; or you can turn off the displaying of all the layers (by clicking on the "eye" in the Layers dock) except the OpenStreetBugs layer.

Upload

Work Offline

Quit

Edit

Some of these menu items will only be active if objects are selected on the map and some are duplicated on the Toolbar.

Undo

Reverts changes starting with the last operation performed (Shortcut: Ctrl-z). The current changes are listed in the Undo dock, with the latest changes at the bottom of the list.

Redo

Reverses an Undo operation by reverting the changes (Shortcut: Ctrl-y).

Cut

Puts the selected object and any Tags into an internal buffer and removes the object from the map (Shortcut: Ctrl-x). Note that this operation does not remove any nodes on a selected way unless they are also selected (see Include children in selection for an easy way to select all of them).

Copy

Puts the selected object and any Tags into an internal buffer but leaves the selected object and Tags intact (Shortcut: Ctrl-c).

Paste Feature(s)

The reverse of a Cut operation (Shortcut: Ctrl-v,f). The object and any Tags in the internal buffer are placed back on the map at the previous location.

Paste Tags (Merge)

The Tags in the internal buffer are merged with the Tags of the currently selected object (Shortcut: Ctrl-v,m).

Paste Tags (Overwrite)

The Tags in the internal buffer replace all the Tags of the currently selected object (Shortcut: Ctrl-v,o).

Remove

Deletes the selected object and any Tags (Shortcut: Del). A popup dialog will appear asking if you also wish to delete all the nodes of the object.

Move

Puts the cursor into Move mode (Shortcut: Ctrl-m). Move an object by left clicking on it and drag it to a new location on the map.

Rotate

Puts the cursor into Rotate mode (Shortcut: Ctrl-a). Rotate an object by left clicking on it and dragging it in a circular direction.

Scale

Puts the cursor into Scale mode. Change the size of an object by left clicking on it and dragging it to the new size.

Extrude

Puts the cursor into Extrude mode (Shortcut: Ctrl-x). Left clicking and dragging on a way between two nodes will move that section of the way while still remaining attached to the two nodes.

Select

Puts the cursor into Select mode (Shortcut: Esc). Left click on an object to select it. Add additional objects to the selection by pressing the Shift key or the Ctrl key then left clicking on them. Pressing the Ctrl key then left clicking on a selected object will unselect it. Left clicking anywhere on the map that's not an object will unselect all the previously selected objects. Dragging the cursor over a section of the map will select any objects within the drag area.

Find

Search for an object within the current map.

View

Gps

Layers

Create

Some of these menu items are duplicated on the Toolbar.

Node

Puts the cursor into Node mode (Shortcut: Ctrl-n). Left click on the map to create a node at that location.

When a node is created, it will be automatically selected and you can input any Tags in the Properties dock that appears to the left of the map.

Road

Puts the cursor into Road mode (Shortcut: Ctrl-r). Left click on the map to create the first node of the road (the way). Move the cursor and left click on the map to create the next node of the road... and so on.

Click on the Select icon on the tool bar (Shortcut: hit Esc) to end the operation.

The direction you create the road is the direction of travel of the road. See Reverse to modify it to go in the other direction.

The newly created road will automatically be selected and you can input any Tags in the Properties dock appears to the left of the map.

Double carriage way

A dock will appear to the left of the map that allows you to change the direction of travel and the distance between the two roads.

Left clicking on the map will create the first node of a double carriage way. Move the cursor and left click again to create the next node... and so on.

Click on the Select icon on the tool bar (Shortcut: hit Esc) to end the operation.

You must select each road of the carriage way to input it's Tags in the Properties dock.

Roundabout

Puts the cursor into Roundabout mode. Left clicking on the map will place a roundabout. Moving the cursor will then change the size of the roundabout. Left clicking again will end the operation and automatically select the roundabout. Input any Tags in the Properties dock that appears to the left of the map.

Rectangle

Puts the cursor into Rectangle mode. Left clicking on the map will place a rectangle. Moving the cursor will then change the size of the rectangle. Left clicking again will end the operation and automatically select the rectangle. Input any Tags in the Properties dock that appears to the left of the map.

Polygon

Puts the cursor into Polygon mode. A popup dialog will ask for the number of sides in the polygon. Then left clicking on the map will place the polygon. Then moving the cursor will determine it's size. Left click again to end the operation.

You must select the polygon to input any Tags in the Properties dock.

Area

Puts the cursor into Area mode. Left click on the map to create the first node of the area. Left click again on the map to create the next node... and so on, until you left click again on the first node. A popup dialog will then appear asking if you wish to create a hole in the area.

The area will be automatically selected when you're finished and you can input any Tags in the Properties dock that appears to the left of the map.

Relation

Feature

The items that are active in this menu depend on the objects being selected on the map, among other things

Include children in selection

Add the nodes on a selected way to the selection.

Force Delete

If the selected node, road, or relation is not "dirty" (doesn't appear in the Undo dock), then remove the object. This operation only works with a single selected object. Warning: This operation can not be reverted by an Undo operation.

Force Upload

Commit the selected feature from a non-uploadable layer (e.g. Track or Extract) to the dirty layer, ready for upload.

OpenStreetBugs

After fixing the OpenStreetBug(s), selecting the OpenStreetBug icon on the map will activate this menu item. If you then click on the OpenStreetBug => Close menu item it will notify the server that the bug is fixed. See Download OpenStreetBugs about downloading the bugs.

Node

The items that are active in this menu depend upon nodes, and sometimes the number of nodes, you currently have selected on the map.

Merge

Select two or more nodes and they become one. Handy for resolving "nodes on the same spot" errors.

Align

Straighten nodes. Select three or more nodes to align by clicking on them while holding the Shift (or Ctrl) key. The selected end nodes determine the alignment if the nodes are connected to a way. The first two nodes selected determine the alignment if the nodes are individual (not connected to a way).

Spread

Straighten nodes and make them equidistant from each other. Select three or more nodes by clicking on them while holding the Shift (or Ctrl) key. The selected end nodes determine the alignment if the nodes are connected to a way. The first two nodes selected determine the alignment if the nodes are individual (not connected to a way).

Detach

Detach a node from a way. Select one or more nodes on a way and then click on the Detach item in the Node menu. The node(s) will become detached and the way will either snap to the remaining nodes and/or "retract" if an end node was selected. See Detaching a node from a way for more information.

Road

The items that are active in this menu depend upon the types (nodes, ways, areas, etc), and sometimes the number, of objects you currently have selected on the map.

Split

Split the selected way into segments. Each segment will still be connected after the operation but have separate Tags. See: Splitting a road.

Break apart

Join

Combine selected (but separate) ways that share a common node into a single way. This will also merge the Tags for the ways. See: Joining two roads.

Reverse

Reverse the direction of travel on a way (For example: A one way street).

Simplify

Remove nodes on the selected ways that serve no purpose. For example, if the selected roads have multiple nodes within a very straight section (not defining a curve), and are not junction nodes, they will be deleted.

Create Junction

Create a junction node that connects selected ways that touch but are not currently connected. For example, if two roads currently cross each other but have no common node, this will create a node that connects them where they cross. The Tags for the ways are not changed.

Add street numbers (Karlsruhe Schema)

This works in the same manner as creating a normal road, but additionally creates parallel ways on both sides of the new road that can be used for address interpolation. Clicking on the new road allows the input of it's tags in the Properties dock, and clicking on each of the parallel ways allows the input of address tags in the Properties dock.

Subdivide

Add X number of equidistant nodes between two adjacent selected nodes on a selected way. A popup dialog will appear asking for X.

Join Areas

Join two selected areas that share a common way. The Tags from the two areas will be merged in the new joined area.

Relation

Add member

Remove member

Remove a member from a relation. This operation works similar to adding a member. But if you select objects that are currently a member of the relation, and then click on this menu item, the object will be removed from the relation. The object is only removed from the relation, not from the map.

Tools

Style

Tag templates

Shortcut Editor...

World OSB Manager...

The World OSB Manager allows to basically have the
entire planet directly available offline, without a database.

The planet is subdivided in regions, which are downloaded and saved in a
binary format (OSB).

The World OSB Manager manages the download of the regions and the conversion in OSB format. The files are saved in the directory you specify ("World directory").

Select "Show grid" to display the grid of Regions. Regions already downloaded are hashed in green.

Click regions to tag them for download (blue hashing).

Click several time, until there is no hashing, to delete a region.

Click "Apply" to start the actual download from the API.

Thereafter, you can open the "world.osb" file in this directory, and every
regions you downloaded will be available for display/change in Merkaartor.

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

More specifically, Merkaartor's implementation is based upon Metacarta Labs implementation of the recommendation in its 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 accidental moving.

If you drop the node on another node a popup dialog will appear asking if you wish to merge the nodes.

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.

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 accidentally 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.

Splitting an area

First select an area (a closed way) by clicking on it. Then select two nonadjacent nodes on the area by clicking on them while holding the Shift (or Ctrl) key. Now click on the Split Area item in the Road menu. A new way will be created between the two selected nodes and the area will be split into two independent areas sharing the new common way. Both areas contain the same Tags the previous area possessed.

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).

Adding an object to a relation

To add e.g. a bus stop to a bus relation you must select the whole relation and the new object, then use the menu command "Relation, Add member".

In more detail: first make sure that you can see the Features dock. If you can't find it make it visible via "Window, Docks, Features". In that dock select the Relations tab and look for the relation you want to edit. Then select the object you want to add to a relation by clicking on it. Make sure that only this object is selected. Then look for the relevant relation in the relations-window to the right, right-click it and click "Add to selection". As a final step use the menu command "Relation, Add member".

Keyboard Shortcuts

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

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 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 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: <Projection name="UTM 15N NAD83 (epsg:26915)" >+proj=utm +zone=15 +ellps=GRS80 +datum=NAD83 +units=m +no_defs </Projection>.

Start up Merkaartor and go to View>Set Projection. You should see your new SRS listed there.