source: subversion/applications/utils/osmosis/plugins/tagtransform/help.txt @ 29793

Last change on this file since 29793 was 18977, checked in by achmyr, 10 years ago

Adding tag-transform-change task, applicable for OSC files format.

File size: 8.6 KB
Line 
1= Tag Transform Plugin =
2
3The tag transform Osmosis plugin allows arbitrary tag transforms to be applied to OSM
4data as a preprocessing step before using other tools. This allows other tools to concentrate
5on doing what ever they do, without having to handle numerous different tagging schemes
6and error corrections.
7
8The transforms apply regular expressions to both the tag keys and values, and enable
9customising output tags based on sub-matches.
10
11== Downloading ==
12
13The plugin is currently available [http://dev.openstreetmap.org/~random/tagtransform.jar here]
14
15The code is GPL and available from OSM svn:
16  http://svn.openstreetmap.org/applications/utils/osmosis/plugins/tagtransform
17
18
19== Installation ==
20
21To install the plugin, place the tagtransform.jar file somewhere on your file-system. Somewhere
22near osmosis maybe a good idea.
23
24To automatically have osmosis load the plugin, edit either your /etc/osmosis or ~/.osmosis file
25to show:
26 OSMOSIS_OPTIONS="-p uk.co.randomjunk.osmosis.transform.TransformPlugin"
27
28You also need to add the plugin to your classpath.
29
30A suggested solution is:
31  cd <osmosis dir>
32  mkdir plugins
33  mv <whereever it is>/tagtransform.jar plugins/
34
35Edit the bin/osmosis file -- on the EXEC= line, replace with:
36  EXEC="$JAVACMD $JAVACMD_OPTIONS -cp $MYAPP_HOME/osmosis.jar:$MYAPP_HOME/lib/mysql-connector-java-5.0.7-bin.jar:$MYAPP_HOME/lib/postgresql-8.3-603.jdbc4.jar:$MYAPP_HOME/lib/postgis_1.3.2.jar:$MYAPP_HOME/plugins/* $MAINCLASS $OSMOSIS_OPTIONS $@"
37
38
39== Running a transform ==
40
41The tasks provided are:
42
43====--tag-transform-change (--ttc)====
44Transform the tags in the change input stream according to the rules specified in a transform file.
45Actually all rules the same as for *tt* task with the only difference: *ttc* task is applicable for _OSC files_
46and transforms tags in every MODIFY or CREATE action.s 
47
48
49====--tag-transform (--tt)====
50Transform the tags in the input stream according to the rules specified in a transform file.
51
52{| class="wikitable"
53|-
54! Pipe
55! Description
56|-
57| inPipe.0
58| Consumes an entity stream.
59|-
60| outPipe.0
61| Produces an entity stream.
62|}
63
64
65{| class="wikitable"
66|-
67! Option
68! Description
69! Valid Values
70! Default Value
71|-
72| file
73| The name of the file containing the transform description.
74|
75| transform.xml
76|-
77| stats
78| The name of a file to output statistics of match hit counts to.
79|
80| N/A
81|}
82
83== Specifying a transform ==
84
85Transforms are specified as an XML file containing a series of translations. Each translation is made up of the
86following parts:
87
88{| class="wikitable"
89|-
90! Part
91! Required
92! Description
93|-
94| name
95|
96| Name of the translation -- used in stats output
97|-
98| description
99|
100| Description of the translation for your own sanity and stats output
101|-
102| match
103| '''Y'''
104| Specifies the conditions that must be met for the output to be applied
105|-
106| find
107|
108| Specifies extra tags used in output that are not essential to achieve a match
109|-
110| output
111|
112| Specifies the tags to be output when an entity is matched
113|}
114
115Translations are executed on each entity, with the output of the first translation used as the input for the second etc.
116
117 
118=== match and find ===
119
120There are a couple of different match types. The top level element must be ''match'' or ''find''.
121
122==== match ====
123
124The match element groups together other matches. It has two modes:
125* '''and''' (default) -- all contained matches must match (checking will stop at the first non-match)
126* '''or''' -- only one of the contained matches must match (all are checked regardless)
127
128'''find''' is a special case of '''or'''-mode and can only be used as a top level tag.
129
130The entity type to enable matches for can also be specified. Valid values are '''all''' (default), '''node''', '''way''',
131and '''relation'''.
132
133The user name and/or user id can also be specified in the match using '''user'''
134and '''uid''' properties respectively.
135
136==== tag ====
137
138Matches individual or groups of tags. Tags are selected by regular expressions. These are standard
139Java regular expressions, and full information can be found at [http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html].
140
141Attributes are used to specify the regexes:
142* '''k''' the key regex to match
143* '''v''' the value regex to match
144* '''match_id''' the ID to reference in output
145
146The output may reference matches to output tags using the specified ID. Any groups extracted by the regex will be available to
147the output.
148
149==== notag ====
150
151Matches on non-presence of tags. If any tag is matched by the regexes then a parent And matcher will fail.
152
153* '''k''' the key regex to not match
154* '''v''' the value regex to not match
155
156=== output ===
157
158The output is specified as a series of operations which are executed in order. Tag keys are considered unique, and so
159any operation writing to an existing key will overwrite that existing tag.
160
161'''If no output section is specified then any matching entities will be dropped entirely
162
163==== copy-all ====
164Copies all the original tags to the output unchanged.
165
166==== copy-unmatched ====
167Copies any tags not matched by match or find expressions.
168
169==== copy-matched ====
170Copies any tags which were matched by match or find expressions.
171
172==== tag ====
173Output a specific tag, or multiple tags if referencing a match. The key and values for the new tag(s)
174are specified using output expressions. Within an output expression '''{0}''' will be replaced with
175the matched regex group of that number. 0 represents the whole match string, and the 1st matched group
176will be output by {1}.
177
178The attributes used are:
179* '''from_match''' -- the match_id to take values from
180* '''k''' -- the key to output
181* '''v''' -- the value to output
182
183If the referenced match doesn't exist (ie: it was part of find or an "or" mode match and no matching tags
184were found) then the tag output is omitted (even if groups aren't used in the strings).
185
186If no match is referenced at all then the key and value are treated as simple strings and output
187verbatim.
188
189
190=== Examples ===
191
192Many applications may require considerably less access types than are available (or frequently
193mistyped):
194 <?xml version="1.0"?>
195 <translations>
196 
197  <translation>
198    <name>Simplify Access</name>
199    <description>Simplifies the access restrictions to yes/no. We could limit for specific keys, but lets live dangerously.</description>
200    <match mode="or">
201      <tag k=".*" match_id="yes" v="true|designated|public|permissive"/>
202      <tag k=".*" match_id="no" v="false|private|privat"/>
203    </match>
204    <output>
205      <copy-all/>
206      <tag from_match="yes" v="yes"/>
207      <tag from_match="no" v="no"/>
208    </output>
209  </translation>
210 
211 </translations>
212
213(XML surround omitted from now on for clarity)
214
215Convert a crossing tagged using the wiki-voted crossing scheme into the heavily used crossing=toucan used
216in rendering the cyclemap:
217  <translation>
218    <name>->Toucan</name>
219    <description>Convert wiki-voted crossings to toucans, and short-cut the crossing_ref case too</description>
220    <match mode="or" type="node">
221      <match>
222        <tag k="crossing" v="traffic_signals"/>
223        <tag k="bicycle" v="yes"/>
224      </match>
225      <tag k="crossing_ref" v="toucan"/>
226    </match>
227    <output>
228      <copy-all/>
229      <tag k="crossing" v="toucan"/>
230    </output>
231  </translation>
232
233There have been many ways of entering cycle routes suggested... we tend to use relations now,
234but lets regularise the legacy way tagging to ensure ncn=yes is placed on all ways
235  <translation>
236    <name>NCN</name>
237    <description>Find all the way ncn way variations and tag consistently</description>
238    <match>
239      <match mode="or">
240        <!-- this matches route=ncn, as well as route=bus;ncn etc. -->
241        <tag k="route" v="(.*;|^)ncn(;.*|$)" match_id="route"/>
242        <!-- sometimes ncn_ref has been specified without ncn=yes -->
243        <tag k="ncn_ref" v=".*"/>
244      </match>
245      <!-- don't match where ncn was already set to something else -->
246      <notag k="ncn" v=".*"/>
247    </match>
248    <output>
249      <copy-all/>
250      <tag k="ncn" v="yes"/>
251      <!-- output the route tag, but without the ncn part -->
252      <tag k="route" from_match="route" v="{1}{2}"/>
253    </output>
254  </translation>
255
256I might not like the prefixes used by the piste:lift scheme for whatever reason. Lets remove them:
257  <translation>
258    <name>Arbitrary Piste Remapping</name>
259    <description>Remap the piste:lift:* style tags to reduce tag length and remove ":" which aren't playing nice with tool X</description>
260    <match type="way">
261      <tag k="piste:lift" v=".*" match_id="type"/>
262    </match>
263    <find>
264      <tag k="piste:lift:(.*)" v=".*" match_id="piste_attr"/>
265    </find>
266    <output>
267      <copy-unmatched/>
268      <tag from_match="type" k="piste_lift"/>
269      <tag from_match="piste_attr" k="{1}" v="{0}"/>
270    </output>
271  </translation>
Note: See TracBrowser for help on using the repository browser.