Pl:JOSM/Plugins/CommandLine

From OpenStreetMap Wiki
Jump to: navigation, search
Dostępne języki — JOSM/Plugins/CommandLine
· Afrikaans · Alemannisch · aragonés · asturianu · azərbaycanca · Bahasa Indonesia · Bahasa Melayu · Bân-lâm-gú · Basa Jawa · Baso Minangkabau · bosanski · brezhoneg · català · čeština · dansk · Deutsch · eesti · English · español · Esperanto · estremeñu · euskara · français · Frysk · Gaeilge · Gàidhlig · galego · Hausa · hrvatski · Igbo · interlingua · Interlingue · isiXhosa · isiZulu · íslenska · italiano · Kiswahili · Kreyòl ayisyen · kréyòl gwadloupéyen · Kurdî · latviešu · Lëtzebuergesch · lietuvių · magyar · Malagasy · Malti · Nederlands · Nedersaksies · norsk bokmål · norsk nynorsk · occitan · Oromoo · oʻzbekcha/ўзбекча · Plattdüütsch · polski · português · português do Brasil · română · shqip · slovenčina · slovenščina · Soomaaliga · suomi · svenska · Tiếng Việt · Türkçe · Vahcuengh · vèneto · Wolof · Yorùbá · Zazaki · српски / srpski · беларуская · български · қазақша · македонски · монгол · русский · тоҷикӣ · українська · Ελληνικά · Հայերեն · ქართული · नेपाली · मराठी · हिन्दी · অসমীয়া · বাংলা · ਪੰਜਾਬੀ · ગુજરાતી · ଓଡ଼ିଆ · தமிழ் · తెలుగు · ಕನ್ನಡ · മലയാളം · සිංහල · ไทย · မြန်မာဘာသာ · ລາວ · ភាសាខ្មែរ · ⵜⴰⵎⴰⵣⵉⵖⵜ · አማርኛ · 한국어 · 日本語 · 中文(简体)‎ · 吴语 · 粵語 · 中文(繁體)‎ · ייִדיש · עברית · اردو · العربية · پښتو · سنڌي · فارسی · ދިވެހިބަސް
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 .