This blog post is part of a series of blog posts about the new OSM file format “OMA”. This is the third post. At the end of the article you’ll find links to the other blog entries.

 

Until now you’ve got a general idea of what the Oma file format is, and an idea of how to use it. But you do not know, where to get an Oma file from.

Well, I hope, that sooner or later someone like Geofabrik will provide a daily updated planet.oma and some excerpts. That would make sense, because converting the data takes a lot of resources, and it would be a waste if everyone had to do it themselves.

But until we have such a distributor, you have to convert OSM files to Oma files on yourself. I have written a converter for this purpose. It’s written in Java and should be easy to use.

 

The Converter

You need a copy of oma.jar. If your are using Linux (or any other Unix operating system) you just have to type the following command:¹

java -Xmx<some number>G -jar oma.jar <some osm file>

The -Xmx part tells the Java Virtual Machine to use <some number> gigabytes of memory. For example, my computer has got 4GB of main memory, so I’ll use -Xmx3G, reducing the available memory by 1GB, because the operating system needs some memory too.

The osm file mentioned in the command, can be one of .osm, .o5m or .pbf².

Well, that’s about it. The program will read the file and start the conversion. This can take a long time, and hopefully it won’t crash.

Huh, crash? I wish I could give you better news, but unfortunately I have not been able to write a program that does never crash. The reason for this is that Java gives no guarantees or means of dealing with out-of-memory situations.³ So: If you have enough memory (and disk space), a crash should never happen, but if you have only limited memory, a crash might be possible.⁴

If the program crashes: Try restarting your computer (this removes memory segmentation) and/or using less(!) memory. In this case it’s also a good ideas to stop doing anything else on the computer while the conversion process is running.

There are some options you can pass to the program. For example, you can use -p to tell the program which meta information to include in the output file. Type java -jar oma.jar --help to get a complete list.

I recommend to try the program with smaller files first, using the -v switch, to get a feeling for what it does.

 

Beneath the Surface

I’ll end this post with a brief description of what happens during the conversion.

Conversion is done in three steps.

The first step reads the input file and splits the data into five parts: nodes, ways, ways created from relations, areas created from relations and collections created from relations. Next, it replaces most of the node and way references with coordinates of the nodes and ways, and finally it merges everything together, making some more changes related to relations. I’ll go into more detail on this in a separate post on relations.

The second step reorders the elements in the file: Each element is put into a geographically bounded chunk.

The third step analyses the elements and tries to determine the type of the element (highway, landuse, building, etc.) In the case of ways, it uses this type to determine whether the element is a real way or an area. It also uses this information to sort the elements once more, this time into blocks and slices.

If you are curious about the inner workings of the converter, try using the -v flag three or four times. You’ll get lots of messages about what’s going on during the conversion.

See also

• A New File Format for OSM Data
• Using the Oma Library
• The OMA File Format
• Dealing with Relations in Oma Files
• Sorting into Chunks
• About main keys and values
• Summary, Outlook and a Real-Life Example

---

1. I’m not familiar with other operating systems. Since Java is independent of the operating system, chances are good, that it will work with other operating systems too, and I guess that the call wouldn’t be much different. ↩

2. Reading pbf files is a bit experimental. In particular, some features of this format are not implemented because I couldn’t find any examples. In practice, it worked whenever I used it. ↩

3. According to the specs, Java’s OutOfMemoryError can happen at any time. In practice, it usually only happens, when you try to allocate new memory. You would like to know ahead of allocation, if it will work. Unfortunately, Java doesn’t provide a way to tell you. You could query the total amount of memory available, but even if it’s larger than the amount you need, that doen’t mean, that the allocation won’t fail (due to memory segmentation). Next you’d expect, that if the allocation would fail, Java would start the garbage collector, before giving up. Nope, false hope. Java doesn’t do that. Even, if you start the garbage collector yourself, there’s no guarantee that it will run. (Fortunately, in practice it does. So I’m using this, but it slows everything down.) If you’ve read this far and you’ve got an idea on how to improve this, I’d love to hear it! ↩

4. Disk space is intentionally not checked. Make sure you have enough before running the program. ↩