Welcome to the JOSM online help system

This help portal can be corrected at josm.openstreetmap.de/wiki/Help
Some information might be outdated, because JOSM is constantly enhanced with more features and tools. Recently implemented features may miss good illustrations, animations, examples and text explanation. Please help improving by adding them or your personal tips and experience - this is a wiki!

Table of Contents

1. Getting Started
   1. Your first edits with JOSM
   2. OSM-wiki resources
   3. Other channels
2. Concepts
   1. OSM data model
   2. Changesets
   3. JOSM concepts
3. Workflow examples
4. JOSM Extensions
5. Recent changes
6. JOSM tools (incomplete reference)
   1. Basic shape of objects
   2. Selection
   3. Tags
   4. Topology tools and changes
   5. Geometry tools
   6. Viewport control
7. JOSM interface
   1. JOSM interface overview
   2. JOSM starting screen
   3. JOSM interface complete reference
   4. JOSM interface customization

Getting Started

Your first edits with JOSM

• Introduction to JOSM - briefly covers downloading data, enabling and aligning imagery, main menu items, presets, validation, change-set comments and upload dialogue
• Migration assist from iD, Potlatch2 or Vespucci - only if you have difficulties or questions related to respective editor "I'm used to do (function) in (an editor) but what should I do in JOSM?"

OSM-wiki resources

• ​Where to get help? - more general articles and resources (including ​Map features)

Other channels

• JOSM channels

Concepts

OSM data model

• Objects (complete reference) - explains what node, way, relation and tag is; Presets are introduced at the same page.
• There are many types of relations, currently loaded relations can be selected via Relations but there a single interface to edit them

Changesets

Changesets exists for every of your "edit". They simply group data creations, modifications and deletions - with additional properties comment, created_by, imagery_used ​and several others (this information stored as simple tags). Similar to other wiki software, one changeset can affect one object (a single character edit in the text), but may contain big changes (removals of paragraphs, partial or complete rewrite of the text) with the only difference that geo information is edited instead of text. Investigating history of one character is equally hard to comparing text at given point in time. Since ​complete "text" in OSM is 30-600GB big therefore users speak of history within several changesets and not about complete history every time.

Upload changeset dialog - explains why you create a changeset and low level details about protocol that uploads data to the OSM server

JOSM concepts

• Hotkeys or shortcuts (complete reference). EVERY "button" and menu item may be assigned with hot-key (including menu items provided with plugins; popular presets and saved search queries). Some of the default hotkeys or activation steps may be surprising. All active shortcuts will be present under "Hotkeys" tab in F12 menu you can adjust and fine-tune them or reset at any moment.
• Preferences (complete reference) - some of the settings are unaccessible via settings menu or have control elements and menus everywhere in the editor
• Undo/redo mechanism - used to spot mistakes, but these tools are especially useful when learning new tools in JOSM. Similar to other editors, most operations in JOSM can be undone and redone, unless they are listed in [Help/Listofirreversibleoperations list of irreversible operations]. Difference is that all changes can be displayed in command stack dialog.

Workflow examples

• Help/Downloading data - there are many ways to load existing data in JOSM
• Help/Relations - relation editing may involve multiple windows (Relations window, Selection, Relation editor) in JOSM. Some plugins may simplify some steps, but provide less clarity about what you do: many tools, states or tags become "hidden" or even worse: simply unaccessible.
• Operating multiple JOSM at once - you are not limited to run one copy of JOSM, unfortunately we don't have any details about it yet (please help us if you are working this way)
• Audio mapping: playing voice notes and synchronizing them with your GPS tracks in JOSM
• Validator messages - will explain how to fix common mistakes and what do they mean
• How to create runabout from crossing ways

JOSM Extensions

JOSM Extensions and installation steps

Recent changes

JOSM is in constant development and many features are implemented every year, you can miss some of its recently implemented features

• Startup notes - most important changes
• Summarized changelog - nicely summarized
• SVN changelog - very detailed, knowledge of Java may be necessary

JOSM tools (incomplete reference)

List below contains mosty/only unreplaceable tools with preference to core JOSM tools. "Incomplete" should be stated explicitly to avoid misunderstandings from any part.

Search among all JOSM tools and menu items - Ctrl+Spacebar

Basic shape of objects

• Select, move and rotate tools - you only need subset of tools from this list
• Draw a rectangular stub - optionally aligned along by other objects
• FastDraw - useful with natural objects;
• Extrude, Angle snapping, ​Spline or Bezier ''from commandline plugin'' - mostly for man made objects
• both Draw nodes mode and Improve Way Accuracy mode - have their followers and use cases
• Paste previously copied objects - not only tags but also their geometries

Selection

Selection (or list of currently selected objects) is precisely described in Help/Dialog/SelectionList#Selection (because it is visible from this dialogue), it can be modified with following tools (incomplete list):

• Select objects - contains many modifiers, including lasso mode
• Search - a very powerful tool and a query language with over 28 keywords and flexible operators to combine them in flexible manner. Not to mention regex and mapcss filters.
• (Shift+F3) - search objects by preset
• Help/Plugin/UtilsPlugin2 - multiple selection focused tools from UtilsPlugin2
• Select non branching way sequences - useful when editing highways, railways, rivers, power networks and networks in general
• Select all is more useful after you download precise list of objects

Tags

Tags of currently selected objects displayed in Tags/Memberships Dialog.

• Copy - copy selected objects to the buffer
• PasteTags - paste previously copied tags
• Tabular editor (Ctrl+T) (from UtilsPlugin2)
• (Shift+R) (from UtilsPlugin2) copy tags from previous selection
• Standard Add value (Alt+A) dialogue provides 5 shortcuts to 5 last used tags without closing this dialogue

Topology tools and changes

• Merge two or more points
• UnGlue explode single point into multiple
• Join point into a way segment
• DisconnectNodeWay - opposite of above, disconnect a node from a way segment
• AddIntersections (Shift+I) (from UtilsPlugin2) - will create nodes at places where current selections intersects (or self intersects)
• Split geometry by selected line (Alt+X) (from UtilsPlugin2)
• Split way - split way by a node
• Combine Way - combine several selected ways in one
• Join overlapping areas
• ContourMerge mode can used to glue complex parts that would require too many Merges otherwise; it could also used to partially or completely replace geometry of one object with partial or a complete geometry of other object

Geometry tools

Precision in angles

• Anglesnapping will ease drawing way segments in 30°, 45°, 60° and 90° degrees
• Extrude tool will ease drawing of strictly perpendicular segments

Alignment

• Align in line will align selected nodes into a line
• Distribute as above, but also place them at equal distances
• "Copy" objects at precise anchor points from ​commandline
• "Move" objects at custom vector from ​commandline
• Align selected nodes in circle

Parallel

• Parallel, draw lines and curves parallel to each other, draw nested infrastructure quickly
• Extude mode used on segments - will move them in parallel, preserving angles when it is needed

Rotation

• Rotate objects at user-defined angle (but exact angle is unknown)
• ShapeTools plugin:
  • Rotate object at predefined angle
  • Rotate objects (match building with road)
  • Rotate objects (match building with road, don't rotate more than epsilon)

Viewport control

• Explained at MapView, "View" menu and Zoom tool
• Minimap window
• JumpToPosition

JOSM interface

JOSM interface overview

Interface terminology (make sure to study bolded items first): Note: Together, 3 and 4 may contain too many items to display at once, use mouse scroll wheel in this case.

1. Main menu 2. Main toolbar (heavily customizable) 3. JOSM modes 4. toggles used to control on/off state of Windows 5. Status bar

6. Slider and scaler 7. Windows (or dialogs) • Layer List • Tags/Memberships • Selection • Relations List • (others) 8. Main editing window 9. Details about [Help/Modes#Activateamode current mode]

JOSM starting screen

1. In JOSM, Help/Downloading data step performed first. For example, use simple Download menu
2. Additional and more complex tools may be activated with Expert mode (also, pay attention to the left side of the screen)

JOSM interface complete reference

JOSM interface - complete reference. Pay attention, that menu pages at this wiki are very deep, just couple of examples below:

• JOSM interface > Help/Menu > Help/Menu/Presets
• JOSM interface > Help/ToggleDialogs > Help/Dialog/TagsMembership - most users will stop here, but actually there are at least two menus: Help/Menu/TagsMembershipMenu#Rightclickonitemsintagspart and Help/Menu/TagsMembershipMenu#Rightclickonitemsinmembershipspart
• JOSM interface > Help/ToggleDialogs > Help/Dialog/LayerList - most users will stop here, but actually there are not two, but 7 menus

JOSM interface customization

See Help/JOSM interface customization for details.