OSMCONVERT(1)

✨ NAME ✨

okay so welcome to the osmconvert(1) era — this is the Converter of OSM files, and honestly? it eats 💅

---

🌸 SYNOPSIS 🌸

osmconvert options [input file]

---

🦋 DESCRIPTION 🦋

So basically this program reads all the different file formats from the OpenStreetMap project and converts your data into whatever output format you picked. glow up for your data, fr fr ✨

💖 These formats can be read:

.osm .osc .osc.gz .osh .o5m .o5c .pbf

🎀 These formats can be written:

.osm (default) .osc .osh .o5m .o5c .pbf

The names of your input files have to be handed over as command line parameters. And bestie, use - if you wanna read from standard input 🫶 You do not need to tell it which input format you're feeding it — osmconvert will clock it all by itself, no notes needed. The output format is .osm by default, and if you want something else you just say so with the matching command line parameter. iconic behaviour only.

---

👑 OPTIONS 👑

• -b=<x1>,<y1>,<x2>,<y2> — wanna limit the geographical region? give it a bounding box, babe. You enter the southwestern corner and the northeastern corner of that area, that's it. For example: -b=-0.5,51,0.5,52
• -B=<border_polygon> — if a bounding box isn't your thing, you can use a border polygon instead to limit the geographical region. The format of a border polygon file lives over in the OSM Wiki: https://wiki.openstreetmap.org/wiki/Osmosis/Polygon_Filter_File_Format You do not have to follow the format description super strictly, but you must make sure that every line of coordinates starts with blanks. that's the one non-negotiable 🫠
• --complete-ways — when you apply a border box or a border polygon, all the nodes outside the borders get excluded — even when they actually belong to a way that isn't entirely excluded, just because it has some nodes sitting inside the borders. This option makes sure every way stays complete, even if it intersects the borders. The tradeoff? Slower processing, and the program loses its ability to read from standard input. They recommend using .o5m format as your input format to compensate for most of that speed disadvantage. worth it though ngl
• --complex-multipolygons, --complex-boundaries — same as above, but multipolygons resp. boundaries will not be cut at the borders either. keeping the whole vibe intact 💅
• --all-to-nodes — some applications literally cannot process ways or relations, they only take nodes as input. But more and more complex objects get mapped as ways or even relations to squeeze all their details into the database. So apply this option if you want to convert ways and relations into nodes and thereby make them available to those nodes-only applications. For each way a node is created. The way's id is increased by 10^15 and taken as the id for the new node. The node's longitude and latitude are set to the way's geographical center. Same applies to relations, however they get 2*10^15 as id offset. math girlboss behaviour 🔥
• --add-bbox-tags — this one adds a tag with a bounding box to each object. The tag will contain the border coordinates in this order: min Longitude, min Latitude, max Longitude, max Latitude. e.g.: <tag k="bBox" v="-0.5000,51.0000,0.5000,52.0000"/>
• --add-bboxarea-tags — adds a tag for an estimated area value for the bbox to each way and each relation. The unit is square meters. For example: <tag k="bBoxArea" v="33828002"/>
• --add-bboxweight-tags — this option adds the binary logarithm of the bbox area of each way and each relation. For example: <tag k="bBoxWeight" v="20"/>
• --add-bboxwidth-tags — adds a tag for an estimated width value for the bbox to each way and each relation. The unit is meters. For example: <tag k="bBoxWidth" v="825"/>
• --add-bboxwidthweight-tags — this option adds the binary logarithm of the bbox width of each way and each relation. For example: <tag k="bBoxWidthWeight" v="10"/>
• --object-type-offset=<id offset> — if you're applying the --all-to-nodes option from above, you might wanna adjust the id offset. For example: --object-type-offset=4000000000 And by appending +1 to the offset, the program will create ids in a sequence with step 1. That can be useful if there's an application running afterwards that can't handle large id numbers. Example: --object-type-offset=1900000000+1
• --drop-broken-refs — use this one if you need to delete references to nodes that got excluded for lying outside the borders. It's mandatory for some applications, e.g. Map Composer, JOSM 🫶
• --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. clean slate energy ✨
• --drop-version — if you want to exclude not only the author information but also the version number, specify this option. double drop, no cap
• --drop-nodes --drop-ways --drop-relations — depending on which combination of these parameters you use, no members of the referred section will be written. bye to whoever you don't want 💀
• --modify-tags=<tag_modification_list> — the tag modification list decides which tags get modified. The example --modify-tags="highway=primary to =secondary" will change every "primary" highway into "secondary". You can also use comparisons or add additional tags: --modify-way-tags="maxspeed>200 add highspeed=yes"
• --modify-node-tags=TAG_MODIFICATION_LIST
• --modify-way-tags=TAG_MODIFICATION_LIST
• --modify-relation-tags=TAG_MODIFICATION_LIST
• --modify-node-way-tags=TAG_MODIFICATION_LIST
• --modify-node-relation-tags=TAG_MODIFICATION_LIST
• --modify-way-relation-tags=TAG_MODIFICATION_LIST

same as above, but just for the object types you named. targeted glow up 💅

• --diff — calculate the difference between two files and create a new .osc or .o5c file. There must be TWO input files and borders cannot be applied. Both files must be sorted by object type and id. Created objects will appear in the output file as "modified", unless they have version number 1. so specific, we love that for us
• --diff-contents — similar to --diff, this option calculates differences between two OSM files. But here, complete OSM objects are consulted to determine the differences, not just the version numbers. Unfortunately this option strictly requires both input files to have .o5m format. no exceptions bestie 😭
• --subtract — the output file will not contain any object which exists in one of the input files following this directive. For example: osmconvert input.o5m --subtract minus.o5m -o=output.o5m
• --pbf-granularity=<val> — rarely, .pbf files come with non-standard granularity. osmconvert will recognize this and suggest you specify the abnormal lon/lat granularity using this command line option. Allowed values are: 100 (default), 1000, 10000, ..., 10000000. we stan a program that warns you nicely 🎀
• --emulate-osmosis, --emulate-pbf2osm — in case of .osm output format, the program will try to use the same data syntax as Osmosis, resp. pbf2osm. matching the group chat aesthetic fr
• --fake-author — if you dropped author information (--drop-author), that data will be lost, of course. Some programs however require author information on input even though they don't actually need that data. For this purpose you can fake the author information. osmconvert will write changeset 1, timestamp 1970. fake it till you make it ✨
• --fake-version — same as --fake-author, but — if .osm xml is used as the 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 is supposed to be deleted. With this option you can have osmconvert fake these values: ... lat="0" lon="0" ... Note that this is for XML files only (.osc and .osh). the drama of it all 💅
• -h — display a short parameter overview. quick lil snack.
• --help — display this help. the full meal 😌
• --merge-versions — some .osc files contain different versions of one object. Use this option to accept such duplicates on input. let them coexist, we're not gatekeeping 🦋
• --out-osm — data will be written in .osm format. This is the default output format. the main character, obviously.
• --out-osc — the OSM Change format will be used for output. Please note that OSM objects which are to be deleted will be represented by their ids only. just the id, nothing else, minimalism 🫠
• --out-osh — for every OSM object, the appropriate 'visible' tag will be added to meet the 'full planet history' specification. history homework, but make it slay
• --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. compact queen 💖
• --out-o5c — this is the change file format of the .o5m data format. All <delete> tags will not be performed as delete actions but converted into .o5c data format. plot twist 🔥
• --out-pbf — for output, PBF format will be used. short king.
• --out-csv — a character separated list will be written to output. The default separator is Tab, the default columns are: type, id, name. You can change both by using the options --csv-separator= and --csv=
• --csv-headline — choose this option to print a headline to csv output. a little title card for your data 🎀
• --csv-separator=<sep> — you may change the default separator (Tab) to a different character or character sequence. For example: --csv-separator="; "
• --csv=<columns> — if you want certain columns in your csv list, please specify their names as shown in this example: --csv="@id name ref description" There are a few special column names for header data: @otype (object type 0..2), @oname (object type name), @id @lon, @lat, @version, @timestamp, @changeset, @uid, @user. build your own spreadsheet era 💅
• --out-none — this will be no standard output. This option is for testing purposes only. ghost mode 👻
• --timestamp=<date_and_time>, --timestamp=NOW<seconds_relative_to_now> — if you want to set the OSM timestamp of your output file, supply it with this option. Date and time must be formatted according to OSM date/time specifications. For example: --timestamp=2011-01-31T23:59:30Z You can also supply a relative time in seconds, e.g. 24h ago: --timestamp=NOW-86400. time travel, but make it precise ⭐
• --out-timestamp — okay bestie this is where part 1 of the page cuts off, more on this one coming right up in part 2 🌈

And picking up right where that last one left off: with it set, osmconvert prints just the time stamp of the input file and literally nothing else. Not one extra crumb. 💅

• --statistics — flips on a statistics counter, and the program prints all that statistical data out to stderr. 📊
• --out-statistics — bestie, it's the same as --statistics, except the statistical data gets written to standard output instead. Same tea, different cup. ✨
• -o=<outfile> — reroutes standard output into the file you name. And if you never specified an output format? The program just reads the file name extension and vibes off that. 👀
• -t=<tempfile> — okay so if borders are gonna be applied, or broken references are gonna be eliminated, osmconvert creates and uses two temporary files. This parameter sets their name prefix. The default value is "osmconvert_tempfile". 🗂️
• --parameter-file=FILE — wanna supply one or more command line arguments through a parameter file? Use this option and hand over the file name. Inside that parameter file, parameters must be separated by empty lines. Any line feeds sitting inside a parameter get converted to spaces. And lines starting with // are treated as comments. 🎀
• -v, --verbose — with verbose mode activated, some statistical data and diagnosis data get displayed. And if -v (or --verbose) is the first parameter in the line, osmconvert will display all the input parameters. Full transparency era. 🔍

---

🛠️ TUNING — the glow-up section 💅

So to speed up the whole process, the program uses some main memory for a hash table. By default it uses 1200 MB for storing a flag for every possible node, 150 for the way flags, and 10 relation flags. Every byte holds the flags for 8 ID numbers — meaning in 1200 MB the program can store 9600 million flags. And since there are fewer than 5700 million IDs for nodes at present (May 2018), 720 MB would honestly suffice.

So, for example, you can decrease the hash sizes to like 720, 80 and 2 MB using this option:

--hash-memory=720-80-2

But keep in mind the OSM database is continuously expanding, bestie. It's giving growth mindset. For this reason the program-own default value is higher than what's 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 just enter the amount of memory as a sum, and the program will divide it by itself. For example:

--hash-memory=1000

Those 1000 MiB get split into three parts: 800 for nodes, 150 for ways, and 50 for relations. Slay, it does the math for you. ✨

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 that 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. Not ideal, but it happens. 🙈

The maximum value the program accepts for the hash size is 4000 MiB. And 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. 🚨

There is another temporary memory space which is used only for the conversion of ways and relations to nodes (option --all-to-nodes). This space is sufficient for up to 25 Mio. OSM objects, 400 MB of main memory are needed for this purpose, and 800 MB if the extended option --add-bbox-tags has been invoked. If that's not sufficient, or if you just want to save memory, you can configure the maximum number of OSM objects by yourself. For example:

--max-objects=35000000

The number of references per object is limited to 100,000. That's enough for all OSM files, no cap. But if you're going to create your own OSM files by converting shapefiles or other files to OSM format, this might result in way objects with more than 100,000 nodes. For this reason you'll need to increase the maximum accordingly. Example:

--max-refs=400000

---

🚧 LIMITATIONS (read this one, fr fr)

When you're extracting a geographical region (using -b or -B), the input file must contain the objects ordered by their type: first, all nodes, next, all ways, followed by all relations. And within each of these sections, the objects section must be sorted by their id in ascending order. Order is the moment, okay? 👑

Usual .osm, .osc, .o5m, o5c and .pbf files adhere to this condition. Which means you do not have to worry about this limitation — the files are already serving correct energy. osmconvert will display an error message if this sequence is broken. 💀

If a polygon file for borders is supplied, the maximum number of polygon points is about 40,000.

---

📝 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 marqqs@gmx.eu 🫶

---

🌈 EXAMPLE

osmconvert europe.pbf --drop-author >europe.osm
osmconvert europe.pbf |gzip >europe.osm.gz
bzcat europe.osm.bz2 |./osmconvert --out-pbf >europe.pbf
osmconvert europe.pbf -B=ch.poly >switzerland.osm
osmconvert switzerland.osm --out-o5m >switzerland.o5m
osmconvert june_july.osc --out-o5c >june_july.o5c
osmconvert june.o5m june_july.o5c.gz --out-o5m >july.o5m
osmconvert sep.osm sep_oct.osc oct_nov.osc >nov.osm
osmconvert northamerica.osm southamerica.osm >americas.osm

Look at that pipeline game. Ate. 💅

---

👀 SEE ALSO

• osmfilter(1)
• osmupdate(1)

---

🫶 AUTHORS

osmconvert was written by Markus Weber. Iconic behavior, honestly.

---

That's the whole page, bestie! This one's dated September 2013 and lives in section OSMCONVERT(1) of the manual. Now go convert something and be the main character of your own data pipeline. Byeee! 🌸✨💖