RU:JOSM/Модули/CommandLine

Команда Cut в процессе ввода данных

Команда Replace в процессе действия

Модуль CommandLine (за авторством Hind) добавляет в интерфейс jOSM командную строку (в стиле Rhinoceros/Autocad) с возможностью создания своих команд на любом знакомом вам языке программирования.

Стандартные команды можно скачать здесь. Для установки нужно распаковать их в каталог %appdata%\JOSM\plugins\CommandLine\ (для Windows) или в ~/.josm/plugins/CommandLine/ (для Linux). Файлы нужно класть непосредственно туда, не копируя папку из архива (это проект с GitHub), а войдя в неё. Описание стандартных команд см. ниже.

Использование

Общий принцип

При загрузке jOSM плагин автоматически сканирует каталог JOSM/plugins/CommandLine и загружает описания из xml-файлов. Все успешно загруженные команды попадают в список автодополнения.

Алгоритм действий при работе с плагином:

1. Поставить курсор в командную строку. Это можно сделать кликом мыши или нажатием клавиши Enter.
2. Ввести название команды (после ввода двух символов начнут предлагаться варианты завершения. Чтобы принять вариант, достаточно нажать Enter).
3. Плагин по очереди запросит у вас все необходимые параметры. Если в параметре допускается только один объект, после его указания начнется ввод следующего параметра. Параметр типа length (длины, радиусы и т.п. можно указывать перетаскиванием, при этом значение будет писаться внизу экрана jOSM, в статусной строке)
4. Параметры будут переданы в исполняемый файл так, как описаны в xml.
5. Отработав, команда вернет результат в плагин, и он проведет нужные изменения в активном слое. При этом доступна отмена стандартными средствами jOSM.

Поддерживается история введенных команд в течение сеанса (перемещение по списку осуществляется курсорными клавишами "вверх" и "вниз"). Последнюю выполненную команду можно повторить, введя пустую строку и нажав Enter.

Стандартные команды

Стандартные команды написаны с использованием языка Python и требуют установленного интерпретатора этого языка. Работоспособность проверялась на Python 2.5.4, 2.6.4 и 3.1.3

Arc	Создает дугу по трем точкам и числу сторон.
Arc with axes	Создает дугу и её оси по трем точкам и числу сторон.
Bezier	Создает кривую Безье по контрольным точкам.
Circle	Создает правильный многоугольник с заданным радиусом описанной окружности и числом сторон.
Copy	Создает копии выбранных объектов по опорным точкам.
Cut	Разрезает полигон на два по двум указанным узлам.
Ellipse	Создает эллипс по заданным полуосям, числу сторон и углу поворота.
Fillet	Скругляет выбранные углы в указанной линии с заданным радиусом и числом сторон.
Grid	Создает квадратную сетку заданного шага, покрывающую все выбранные объекты.
Implode	Схлопываает объекты в точки - создает точку в центре каждого выделенного полигона, переносит на нее все теги, после чего удаляет полигон.
Mirror	Создает зеркальное отражение выбранных объектов относительно прямой, заданной двумя точками.
Move	Перемещает выбранные объекты по опорным точкам.
Offset	Производит смещение линии на указанное расстояние вправо, влево или в обе стороны. Многоугольники - расширяет и/или сжимает.
Regexp	Заменяет теги и/или значения согласно введенным регулярным выражениям для поиска и замены.
Replace	Заменяет линии и полигоны по образцу. Автоматически поворачивает объект. Сохраняет историю изменений объекта.
Replace2 (no rotation)	Заменяет линии и полигоны по образцу, сохраняет историю изменений объекта, но не выполняет поворот.
Spline	Создаёт кубический эрмитов сплайн типа Catmull–Rom. Для работы требуется библиотека numpy
TagCalc	(экспериментальный) Проставляет новый тэг всем выделенным объектам, значение тэга вычисляется по формуле (пока поддерживается только конкатенация - тэгов, фиксированных строк и некоторых параметров вроде ширины/долготы точек)

Создание команд

Команда описывается xml-файлом и может иметь произвольное количество параметров.

Формат файла-описателя

Описатель представляет собой файл в формате xml, содержащий описание только одной (временное ограничение) команды.

Тег command

Корневой тег документа. Атрибуты тега:

name	Название команды, по которому она будет вызываться из командной строки.	Обязателен
run	Исполняемая команда. Должна успешно выполняться из каталога JOSM/plugins/CommandLine. Подстроки вида {Название параметра} будут заменены на значения параметров.	Обязателен
icon	Имя файла-иконки. Файл должен находиться в том же каталоге CommandLine.	Не обязателен
tracks	В текущей реализации, если установлен в 'bbox', после всех параметров будут переданы треки в габаритном прямоугольнике переданных osm-объектов	Не обязателен
version	Версия формата описателя. В данный момент '3'	Не обязателен

Тег parameter

Должен находиться в теге command. Описывает отдельный параметр команды. Атрибуты тега:

type	Тип параметра (см. таблицу ниже).	Обязателен
required	Показывает, что параметр обязателен для ввода. Всегда 'true', так как необязательные параметры сейчас не поддерживаются.	Обязателен
maxinstances	Максимальное количество экземпляров значений. Если установлен в '0', количество экземпляров не ограничено. По умолчанию '1'. Сейчас поддерживается только типов node, way, relation, any, point	Не обязателен
mininstances	Минимальное количество экземпляров значений. По умолчанию '1'. Сейчас поддерживается только для osm-объектов и типа point	Не обязателен

Тег name

Должен находиться в теге parameter. Содержит название параметра, доступное для использования в атрибуте run.

Тег description

Должен находиться в теге parameter. Содержит описание параметра, которое будет выведено при его запросе.

Тег relay

Должен находиться в теге parameter. Содержит параметр по умолчанию или (для типа relay) возможные значения. Последний такой тег в этом случае будет параметром по умолчанию.

Пример документа

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

Передача параметров

Существуют параметры трех типов:

1. Объекты OSM (node, way, relation, any). Они передаются в скрипт через стандартный ввод.
2. Параметры с возможностью ручного ввода (number, length, point, relay, string). Они передаются в скрипт как аргумент командной строки.
3. Треки. Передаются в скрипт через стандартный ввод после всех остальных параметров (на текущий момент).

В начале передаются все зависимости аргументов (узлы полигонов, участники отношений и т.п.)

Даже если команда не имеет параметров типа объектов OSM, в начале все равно будет передан пустой osm xml с зависимостями:

<?xml version="1.0" encoding="UTF-8"?>
<osm></osm>

Типы параметров

node	Объект OSM «узел». Не имеет зависимостей.
way	Объект OSM «линия». В зависимостях передаются составляющие узлы.
relation	Объект OSM «отношение». В зависимостях передаются все участники отношения с их зависимостями.
any	Произвольные объекты OSM.
number	Натуральное число. Может быть только введено в командную строку..
length	Положительное число. Может быть введено в командную строку или отмерено на карте перетаскиванием (значение в метрах).
point	Точка. Может быть введена в командную строку (в формате "55.042,37.144") или указана на карте. При этом работает привязка к узлам.
relay	Реле. При вводе можно ввести один из предлагаемых вариантов (полностью или горячей буквой)
string	Просто строка текста. Может быть только введена в командную строку.
username	Имя пользователя в JOSM (логин OSM-аккаунта). Не вводится (подставляется автоматически).
imageryurl	Адрес активного или единственного Imagery-слоя. Не вводится. В случае WMS передается адрес, в случае Bing слово 'bing' и т.п.
imageryoffset	Текущее смещение активного или единственного Imagery-слоя. Не вводится.

Формат ответа

Скрипт должен подготовить и вывести в свой стандартный вывод josm xml. Кратко: новые объекты должны иметь отрицательный id, изменяемые объекты должны иметь атрибут action='modify', удаляемые объекты должны иметь атрибут action='delete'.

На текущий момент все зависимости должны идти перед определяемым объектом, из-за чего, в частности, не поддерживаются перекрестные отношения.

Имеется возможность отправлять в плагин комментарии для сообщения информации пользователю. Комментарии могут передаваться в любой момент, в том числе перед заголовком XML. Например:

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

Ограничения

Из-за того, что вся обработка данных происходит извне jOSM, операции, которые могут затронуть объекты, использующиеся в не переданных скрипту объектах, могут приводить к непредсказуемым последствиям.

Идет работа для обеспечения безопасности. :3

FAQ

После задания необходимых параметров высвечивается Обработка... и висит.

Если это появляется при использовании команд из стандартного набора - то скорее всего у вас не установлен python. Кроме того надо добавить путь к python в системную переменную path (проверить это можно выполнив в командной строке python).

Как можно быстро повторить предыдущую команду

Двойное нажтие клавиши Enter

Написал скрипт для новой команды, как поделиться с сообществом?

Лучше всего средствами github - сделать fork основного репозитория команд, загрузить скрипты туда и отправить pull request в основной репозиторий.