Pl:JOSM/Plugins/CommandLine

Polecenie Cut w trakcie wprowadzania danych

Polecenie Replace w trakcie wprowadzania danych

Wtyczka CommandLine (autorstwa Hind) dodaje do interfejsu JOSM wiersz polecenia (w stylu Rhinoceros/Autocad) z możliwością stworzenia własnych poleceń w dowolnym znanym języku programowania.

Standardowe polecenia można pobrać tutaj. Dla instalacji trzeba rozpakować ich do katalogu %appdata%\JOSM\plugins\CommandLine\ (dla Windows) albo do ~/.josm/plugins/CommandLine/ (dla Linux). Pliki trzeba umieścić tam bezpośrednio, nie kopiując folderu z paczki (to jest projekt GitHub), а otwierając ją. Opis standardowych poleceń patrz niżej.

Użycie

Ogólne zasady

Podczas uruchamiania jOSM wtyczka automatycznie skanuje katalog JOSM/plugins/CommandLine i ładuje opisy z plików xml. Wszystkie pomyślnie załadowane polecenia trafiają do listy auto uzupełnień.

Algorytm postępowania podczas pracy z pluginem:

1. Ustaw kursor w wierszu poleceń. Mona to zrobić poprzez kliknięcie myszką albo naciskając Enter.
2. Wprowadź nazwę polecenia (po wprowadzeniu dwóch symboli będą proponowane warianty dokończenia. Żeby zatwierdzić wariant, wystarczy nacisnąć Enter).
3. Plugin po kolei zapyta o wszystkie niezbędne parametry. Jeśli w parametrze przewidziano tylko jeden obiekt, po jego wskazaniu zacznie się wprowadzanie następnego parametru. Parametr typu length (długość, promień itp. można wskazać poprzez przeciąganie, przy czy wartość będzie widoczna na dole okna jOSM, w pasku stanu)
4. Parametry zostaną przekazane do pliku wykonawczego tak, jak zostały opisane w xml.
5. Po wykonaniu, polecenie zwróci rezultat do pluginu, i on wprowadzi niezbędne zmiany do aktywnej warstwy. Przy tym będzie dostępne wycofanie wszystkich operacji poprzez standardowe narzędzia jOSM.

Wspierana jest historia wprowadzonych poleceń w trakcie sesji (poruszanie się po liście jest możliwe poprzez klawisze strzałek "Up" i "Down"). Ostatnie wprowadzone polecenie można powtórzyć, klikając na puste pole i naciskając Enter.

Standardowe polecenia

Standardowe polecenia zostały napisane w języku Python i wymagają zainstalowanego interpretatora tego języka. Testowano na Python 2.5.4 i Python 3.1.3

Arc	Tworzy łuk z trzech węzłów i liczby segmentów.
Arc with axes	Tworzy łuk i jego osie z trzech węzłów i liczby segmentów.
Bezier	Tworzy krzywą Béziera według punktów kontrolnych.
Circle	Tworzy prawidłowy wielokąt z ustalonym promieniem opisanego okręgu i liczbą segmentów.
Copy	Tworzy kopie wybranych obiektów na podstawie punktów odniesienia.
Cut	Dzieli obszar na dwie części w dwóch wskazanych węzłach.
Fillet	Zaokrągla wybrane kąty we wskazanej linii z ustawionym promieniem i liczbą segmentów.
Grid	Tworzy kwadratową siatkę o określonej szerokości, pokrywającą wszystkie wybrane obiekty.
Implode	Zamienia obiekty na węzły - tworzy węzeł w centrum każdego zaznaczonego obszaru, przenosi na niego wszystkie tagi, po czym kasuje obszar.
Mirror	Tworzy lustrzane odbicie wybranych obiektów względnie prostej, ustanowionej przez dwa węzły.
Move	То samo, co Copy, tylko bez kopiowania.
Offset	Przesuwa linię w prawo, w lewo albo w obie strony.
Regexp	Zamienia tagi i/albo wartości na podstawie wprowadzonych regularnych słów.
Replace	Zamienia linie i obszary na podstawie wzorca. Automatycznie obraca obiekt. Zachowuje historię zmian obiektu.
Replace2 (no rotation)	Zamienia linie i obszary na podstawie wzorca, zachowuje historię zmian obiektu, ale bez rotacji.
Spline	Tworzy Cubic Hermite spline typu Catmull–Rom. Wymagana biblioteka numpy
TagCalc	(eksperymentalny) Dodaje nowy tag do wszystkich zaznaczonych obiektów, wartość tagu jest ustalana na podstawie wzoru (na razie jest tylko wsparcie dla konkatenacji - tagów, linii i niektórych parametrów, takich jak szerokości/długości węzłów)

Tworzenie poleceń

Polecenie jest opisywane plikiem xml i może mieć dowolną liczbę parametrów.

Format deskryptora pliku

Deskryptor pliku stanowi plik w formacie xml, zawierający opis tylko jednego (tymczasowe ograniczenie) polecenia.

'command' tag

The root tag of the document. Tag attributes:

name	Nazwa polecenia, na podstawie którego będzie ono wywoływane z wiersza poleceń.	Konieczny
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 'relay' type) 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.
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.

First, all the parameter dependencies are passed (nodes of ways, members of relations etc.)

Even if the command does not have parameters of types 'way' and 'relation', it will be passed a blank OSM XML without dependencies:

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

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

Ograniczenia

Z powodu tego, że wszystkie dane przetwarzane są poza jOSM, operacje,które mogą mieć wpływ na obiekty, wykorzystywane w nie przekazanych skryptowi obiektach, mogą prowadzić do nieprzewidzianych skutków. Trwają prace nad poprawą bezpieczeństwa. :3

FAQ

Po ustawieniu wymaganych parametrów wyświetla się Loading... i nic się nie dzieje.

Jeśli to się zdarza podczas korzystania z poleceń standardowych - to prawdopodobnie nie zainstalowano python. Oprócz tego trzeba dodać ściekę do python do zmiennej środowiskowej path (sprawdzić to można wykonując w wierszu poleceń python).

Jak szybko powtórzyć ostatnie polecenie

Dwukrotnie naciskamy Enter

Napisałem skrypt dla nowego polecenia, jak się podzielić ze społecznością?

Najlepiej poprzez narzędzia github - zrobić fork głównego repozytorium poleceń, załadować tam skrypty i wysłać pull request do głównego repozytorium .