NAME¶
osmfilter - The experimental OSM filters data
SYNOPSIS¶
osmfilter options [
input file]
DESCRIPTION¶
THIS PROGRAM IS FOR EXPERIMENTAL USE ONLY. PLEASE EXPECT MALFUNCTION AND DATA
LOSS. SAVE YOUR DATA BEFORE STARTING THIS PROGRAM.
This program filters OpenStreetMap data.
The input file name must be supplied as command line argument. The file must not
be a stream. Redirections from standard input will not work because the
program needs random access to the file. You do not need to specify the input
format, osmfilter will recognize these formats: .osm (XML), .osc (OSM Change
File), .osh (OSM Full History), .o5m (speed-optimized) and .o5c
(speed-optimized Change File).
The output format is .osm by default. If you want a different format, please
specify it using the appropriate command line parameter.
OPTIONS¶
--keep=
OBJECT_FILTER
- All object types (nodes, ways and relations) will be kept if they meet the
filter criteria. Same applies to dependent objects, e.g. nodes in ways,
ways in relations, relations in other relations. Please look below for a
syntax description of OBJECT_FILTER.
--keep-nodes=
OBJECT_FILTER
--keep-ways=
OBJECT_FILTER
--keep-relations=
OBJECT_FILTER
--keep-nodes-ways=
OBJECT_FILTER
--keep-nodes-relations=
OBJECT_FILTER
--keep-ways-relations=
OBJECT_FILTER
- Same as above, but just for the specified object types.
--drop=
OBJECT_FILTER
- All object types (nodes, ways and relations) which meet the supplied
filter criteria will be dropped, regardless of meeting the criteria of a
keep filter (see above). Please look below for a syntax description of
OBJECT_FILTER.
--drop-nodes=
OBJECT_FILTER
--drop-ways=
OBJECT_FILTER
--drop-relations=
OBJECT_FILTER
--drop-nodes-ways=
OBJECT_FILTER
--drop-nodes-relations=
OBJECT_FILTER
--drop-ways-relations=
OBJECT_FILTER
- Same as above, but just for the specified object types.
--keep-tags=
TAG_FILTER
- The in TAG_FILTER specified tags will be allowed on output. Please look
below for a syntax description of TAG_FILTER.
--keep-node-tags=
TAG_FILTER
--keep-way-tags=
TAG_FILTER
--keep-relation-tags=
TAG_FILTER
--keep-node-way-tags=
TAG_FILTER
--keep-node-relation-tags=
TAG_FILTER
--keep-way-relation-tags=
TAG_FILTER
- Same as above, but just for the specified object types.
--drop-tags=
TAG_FILTER
- The specified tags will be dropped. This overrules the previously
described parameter --keep-tags. Please look below for a syntax
description of TAG_FILTER.
--drop-node-tags=
TAG_FILTER
--drop-way-tags=
TAG_FILTER
--drop-relation-tags=
TAG_FILTER
--drop-node-way-tags=
TAG_FILTER
--drop-node-relation-tags=
TAG_FILTER
--drop-way-relation-tags=
TAG_FILTER
- Same as above, but just for the specified object types.
--drop-author
- For most applications the author tags are not needed. If you specify this
option, no author information will be written: no changeset, user or
timestamp.
--drop-version
- If you want to exclude not only the author information but also the
version number, specify this option.
--drop-nodes
--drop-ways
--drop-relations
- According to the combination of these parameters, no members of the
referred section will be written.
--emulate-osmosis
--emulate-pbf2osm
- In case of .osm output format, the program will try to use the same data
syntax as Osmosis, resp. pbf2osm.
--fake-author
- If you have dropped author information (--drop-author) that data
will be lost, of course. Some programs however require author information
on input although they do not need that data. For this purpose, you can
fake the author information. o5mfiler will write changeset 1, timestamp
1970.
--fake-version
- Same as --fake-author, but - if .osm xml is used as output format -
only the version number will be written (version 1). This is useful if you
want to inspect the data with JOSM.
--fake-lonlat
- Some programs depend on getting longitude/latitude values, even when the
object in question shall be deleted. With this option you can have
osmfilter to fake these values:
... lat="0" lon="0" ...
Note that this is for XML files only (.osc and .osh).
-h
- Display a short parameter overview.
--help
- Display this help.
--ignore-dependencies
- Usually, all member nodes of a way which meets the filter criteria will be
included as well. Same applies to members of included relations. If you
activate this option, all these dependencies between OSM objects will be
ignored.
--out-key=
KEYNAME
- The output will contain no regular OSM data but only statistics: a list of
all used keys is assembled. Left to each key, the number of occurrences is
printed. If KEYNAME is given, the program will list all values which are
used in connections with this key. You may use wildcard characters for
KEYNAME, but only at the beginning and/or at the end. For example:
--out-key= addr:*
--out-count=
KEYNAME
- Same as --out-key=, but the list is sorted by the number of
occurrences of the keys resp. values.
--out-osm
- Data will be written in .osm format. This is the default output
format.
--out-osc
- The OSM Change format will be used for output. Please note that OSM
objects which are to be deleted are represented by their ids only.
--out-osh
- For every OSM object, the appropriate 'visible' tag will be added to meet
'full planet history' specification.
--out-o5m
- The .o5m format will be used. This format has the same structure as the
conventional .osm format, but the data are stored as binary numbers and
are therefore much more compact than in .osm format. No packing is used,
so you can pack .o5m files using every file packer you want, e.g. lzo,
bz2, etc.
--out-o5c
- This is the change file format of .o5m data format. All <delete>
tags will not be performed as delete actions but converted into .o5c data
format.
-o=<outfile>
- Standard output will be rerouted to the specified file. If no output
format has been specified, the program will proceed according to the file
name extension.
-t=<tempfile>
- osmfilter uses a temporary file to process interrelational dependencies.
This parameter defines the name prefix. The default value is
"osmfilter_tempfile".
--parameter-file=
FILE
- If you want to supply one ore more command line arguments by a parameter
file, please use this option and specify the file name. Within the
parameter file, parameters must be separated by empty lines. Line feeds
inside a parameter will be converted to spaces. Lines starting with
"// " will be treated as comments.
-v --verbose
- With activated 'verbose' mode, some statistical data and diagnosis data
will be displayed. If -v resp. --verbose is the first
parameter in the line, osmfilter will display all input parameters.
OBJECT_FILTER¶
Some of the command line arguments need a filter to be specified. This filter
definition consists of key/val pairs and uses the following syntax:
"KEY1=VAL1 OP KEY2=VAL2 OP KEY3=VAL3 ..."
- OP is the Boolean operator, it must be either "and" or
"or". As usual, "and" will be processed prior to
"or". If you want to influence the sequence of processing, you
may use brackets to do so. Please note that brackets always must be padded
by spaces. Example: lit=yes and ( note=a or source=b ) Instead of each
"=" you may enter one of these comparison operators: != (not
equal), <, >, <=, >= The program will use ASCII-alphabetic
comparison unless you compare against a value which is starting with a
digit. If there are different possible values for the same key, you need
to write the key only once. For example:
"amenity=restaurant =pub =bar"
- It is allowed to omit the value. In this case, the program will accept
every value for the defined key. For example:
"all highway= lit=yes"
- You may use wildcard characters for key or value, but only at the
beginning and/or at the end. For example:
"wikipedia:*=highway=*ary ref_name=*central*"
- Please be careful with wildcards in keys since only the first key which
meets the pattern will be processed. There are three special keys which
represent object id, user id and user name: @id, @uid and @user. They
allow you to search for certain objects or for edits of specific
users.
TAG_FILTER¶
The tag filter determines which tags will be kept and which will be not. For
example :
--keep-tags="highway=motorway =primary"
- will not accept "highway" tags other than "motorway"
or "primary". Note that neither the object itself will be
deleted, nor the remaining tags. If you want to drop every tag which is
not mentioned in a list, use this example:
all highway= amenity= name=
TUNING¶
To speed-up the process, the program uses some main memory for a hash table. By
default, it uses 480 MB for storing a flag for every possible node, 90 for the
way flags, and 30 relation flags. Every byte holds the flags for 8 ID numbers,
i.e., in 480 MB the program can store 3840 million flags. As there are less
than 1900 million IDs for nodes at present (July 2012), 240 MB would suffice.
So, for example, you can decrease the hash sizes to e.g. 240, 30 and 2 MB (for
relations, 2 flags are needed each) using this option:
--hash-memory=
240-30-2
But keep in mind that the OSM database is continuously expanding. For this
reason the program-own default value is higher than shown in the example, and
it may be appropriate to increase it in the future. If you do not want to
bother with the details, you can enter the amount of memory as a sum, and the
program will divide it by itself. For example:
--hash-memory=
1000
These 1000 MiB will be split in three parts: 800 for nodes, 150 for ways, and 50
for relations.
Because we are taking hashes, it is not necessary to provide all the suggested
memory; the program will operate with less hash memory too. But, in this case,
the border filter will be less effective, i.e., some ways and some relations
will be left in the output file although they should have been excluded. The
maximum value the program accepts for the hash size is 4000 MiB; If you exceed
the maximum amount of memory available on your system, the program will try to
reduce this amount and display a warning message.
LIMITATIONS¶
When filtering whole OSM objects (
--keep...=,
--drop...=), the
input file must contain the objects ordered by their type: first, all nodes
nodes, next, all ways, followed by all relations.
Usual .osm, .osc, .o5m and o5c files adhere to this condition. This means that
you do not have to worry about this limitation. osmfilter will display an
error message if this sequence is broken.
The number of key/val pairs in each filter parameter is limited to 1000, the
length of each key or val is limited to 100.
NOTES¶
This program is for experimental use. Expect malfunctions and data loss. Do not
use the program in productive or commercial systems.
There is NO WARRANTY, to the extent permitted by law. Please send any bug
reports to markus.weber@gmx.com
EXAMPLE¶
osmfilter europe.o5m --keep=amenity=bar -o=new.o5m
osmfilter a.osm --keep-nodes=lit=yes --drop-ways -o=light.osm
osmfilter a.osm --keep="place=city or ( place=town and population>=10000
)" -o=b.osm
osmfilter region.o5m --keep="bridge=yes and layer>=2" -o=r.o5m
SEE ALSO¶
osmconvert(1),
osmupdate(1)
AUTHORS¶
osmfilter was written by Markus Weber