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

From OpenStreetMap Wiki
Jump to navigation Jump to search
Команда 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 в основной репозиторий.