JOSM/Plugins/CommandLine

Cut command

Replace command

This page is being translated.

CommandLine plugin (by Hind) adds a command line (like in Rhinoceros / Autocad) to the JOSM editor. It supports commands created with almost any programming language.

Sample commands are available here. Unpack the files from folder "JOSM-CommandLine-commands-master" to the plugin folder (%appdata%\JOSM\plugins\CommandLine\ for Windows, ~/.josm/plugins/CommandLine/ or ~/.local/share/JOSM/plugins/CommandLine for Linux, ~/Library/JOSM/plugins/CommandLine for macOS) to install them. These commands are described below.

Usage

Description

On JOSM startup, plugin scans the plugin directory and loads command descriptions from the XML files. Plugin autocompletes the commands when you type them.

1. Put the cursor on the command line by clicking in it or pressing the Enter key.
2. Start typing the command name. Autocomplete will provide you with the list of matching commands when you type two first characters of the command. To select the command press the Enter key.
3. The plugin requests all the necessary parameters step by step. Measurable parameters (lengths, radii, etc.) can be specified by dragging over the map.
4. The plugin serializes the parameters into XML format described below and executes the command executable.
5. The plugin changes the active layer applying the changes returned by the executable. All actions are not revertible (you cannot undo them) as always in JOSM.

The plugin supports the history of executed commands. The last command can be repeated by pressing Enter when the command line is empty.

Standard commands

Standard commands are created with Python and therefore require Python interpreter to be installed. They have been tested on Python 2.5.4 and 3.1.3.

Arc	Creates an arc by three points and the number of segments.
Bezier	Creates a Bezier curve by control points.
Circle	Creates a regular polygon with a given radius of the circumscribed circle and the number of sides.
Copy	Creates the copies of the selected objects on the pivot points.
Cut	Cuts the polygon into two parts through two selected nodes.
Fillet	Rounds the selected corners in the selected way with a specified radius and number of sides.
Mirror	Mirrors the selected objects relative to the line defined by two points.
Move	Moves the selected objects on the pivot points.
Offset	Shifts the way to the right, left or in the both directions.
Regexp	Replaces keys and/or values according to the entered regular expressions for search and replace.
Replace	Replaces ways (and polygons) upon a pattern. Rotates the object automatically. Saves the object changes history.

Adding new commands

The command is defined by the XML file and may have arbitrary number of parameters.

Descriptor file format

Descriptor is a file in XML format containing a description of a single (at this moment) command.

<command> tag

The root tag of the document. Tag attributes:

name	The command name as seen from the command line.	Mandatory
run	The command to be executed in the system. It must be able to run in the JOSM/Plugins/CommandLine directory. Patterns like {parameter name} will be replaced by parameter values.	Mandatory
icon	Icon filename. This file should be in the same directory.	Optional
tracks	Currently, if set to 'bbox', tracks in a bounding box of passed osm-objects will be passed after all parameters.	Optional
version	Version of the format descriptor. Currently '3'.	Optional

<parameter> tag

Should be placed in the <command> tag. Describes a command parameter. Tag attributes:

type	Parameter type (see table below).	Mandatory
required	Specifies whether the parameter is mandatory. At the moment must be true because optional parameters are not supported yet.	Mandatory
maxinstances	Maximum number of values. If set to 0, number of values is not limited. Default is 1. At the moment, only node, way, relation, any and point types are supported.	Optional
mininstances	Minimum number of values. Default is 1. OSM-object types and point type are supported only.	Optional

<name> tag

Should be placed in the <parameter> tag. Contains the name of parameter that are available for using in the 'run' attribute.

<description> tag

Should be placed in the <parameter> tag. Contains a description of the parameter, which will be displayed at this request.

<relay> tag

Should be placed in the <parameter> tag. Contains the default parameter value or (for the type="relay") possible values. In this case the last such tag is default value.

Descriptor example

<?xml version="1.0" encoding="UTF-8"?>
<command version="3" name="Mirror" run="python mirror.py {First point} {Second point} {Copy}">
	<parameter required="true" type="any" maxinstances="0">
		<name>Objects</name>
		<description>Objects for mirroring</description>
	</parameter>
	<parameter required="true" type="point">
		<name>First point</name>
		<description>First point of mirror line</description>
	</parameter>
	<parameter required="true" type="point">
		<name>Second point</name>
		<description>Second point of mirror line</description>
	</parameter>
	<parameter required="true" type="relay">
		<name>Copy</name>
		<description>Copy</description>
		<value>Yes</value>
		<value>No</value>
	</parameter>
</command>

Parameters passing

There are three types of the parameters:

1. OSM objects (node, way, relation, any). They are passed to the external tool via the standard input. First, all the parameter dependencies are passed (nodes of ways, members of relations etc.). This leads to two concatenated XML documents.
2. Types with possibility of manual input (number, length, point, relay, string). They are passed as system command line argument.
3. Tracks. At the moment, they are passed after all other parameters in GPX format via standard input

You can have up to 3 XML documents concatenated on standard input:

1. object references (always present, empty XML document if there are no references as shown in example)
2. object parameter(s) (present if <parameter> of any OSM object (type= "node", "way", "relation" or "any" is used)
3. tracks (present if tracks="bbox" is used)

<?xml version='1.0' encoding='UTF-8'?>
<osm version='0.6' generator='JOSM'>
</osm>
<?xml version='1.0' encoding='UTF-8'?>
<osm version='0.6' generator='JOSM'>
  <node id='558543487' timestamp='2017-10-01T13:06:53Z' uid='519916' user='googlenaut' visible='true' version='3' changeset='52536250' lat='52.367087' lon='9.7377711' />
</osm>
<?xml version='1.0' encoding='UTF-8'?>
<gpx version="1.1" creator="JOSM GPX export" xmlns="http://www.topografix.com/GPX/1/1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
  <metadata>
    <time>2022-04-19T14:53:15.769Z</time>
  </metadata>
</gpx>

Parameter types

node	OSM object "node". Has no dependencies.
way	OSM object "way". Constituting nodes are passed in dependencies.
relation	OSM object "relation ". Constituting nodes, ways and relations are passed in dependencies.
any	Any OSM object.
number	Natural number. Can be entered only into the command line.
length	Positive number. Can be entered into the command line or measured by dragging on the map view (value in meters).
point	Points. Can be entered into the command line as coordinates ("55.042,37.144") or specified by clicking on the map view.
relay	Switch. Can be entered only into the command line as one letter or full variant name.
string	Just a text string. Can be entered only into the command line.
username	OSM username. Can't be entered.
imageryurl	Url of active or single Imagery layer. Can't be entered. If is WMS layer then parameter equals url, if is Bing layer then parameter equals 'bing' etc.
imageryoffset	Offset of active or single Imagery layer. Can't be entered.

Response format

The external tool must prepare and output JOSM XML data to the stdout.

New objects should have a negative id, modified objects should have the attribute action='modify', removed objects should have the attribute action='delete'. Untouched objects should not occur in the response!

At the moment, all the dependencies should be passed before an object. That's the reason why cross-references are not supported.

You can send text messages to plugin for informing user. They can be sent anytime, including before XML header. For example:

<!--Merging nodes...-->

Restrictions

Due to the fact that all data processing occurs outside JOSM, operations that can affect objects that are used in not passed objects, can lead to undefined consequences.

There's some work in progress to ensure the safety :3

FAQ

How to share script for new command with community?

It is better to use github - fork main repository for commands, commit script files there and send pull request to main repository.