OSM2World

OSM2World

Author:	Tobias Knerr and other contributors
License:	GNU Lesser General Public License (free of charge)
Platforms:	Windows, Linux, and macOS
Version:	0.3.1 (2022-12-29)
Language:	English
Website:	https://osm2world.org
Source code:	https://github.com/tordanik/OSM2World
Programming language:	Java
Creates a 3D model of the world from OSM data.

OSM2World (osm2world.org) is an application that converts OpenStreetMap data to three-dimensional models. The models can be exported to different formats.

Export formats

Currently, .gltf files, Wavefront .obj files, .pov files for the POVRay raytracer, direct output via JOGL (OpenGL bindings for Java) and .png images generated using the JOGL output are supported. Additional formats can be added as needed.

How to use OSM2World

POVRay rendering of OSM2World scene

Installation

OSM2World needs a Java Runtime Environment (JRE) in version 17 or newer (older OSM2World releases require JRE 8). Once you have Java set up, go to osm2world.org/download and get the zip archive with the compiled program. Extract it somewhere on your computer.

Graphical interface

Run OSM2World from the command line with parameter --gui using the batch/script that is appropriate for your system. It allows you to open OSM data files and navigate through the models:

left mouse button moves the camera position
right mouse button rotates the camera direction
mouse wheel moves the camera closer to or away from the ground

Keyboard navigation is available as an alternative. Various debug layers can be displayed, and export to .png, .pov, .gltf and .obj is possible. Be warned that the visualization is low quality and rather performance hungry at the moment, it primarily serves debugging purposes.

Command line interface

This is a short documentation of the OSM2World command line. Please understand that the command line syntax is not yet stable and is likely to change in the future.

Input and output

Result of the PNG export example

-i/--input <file> .osm, .osm.gz, .osm.bz2 or .osm.pbf input files are supported
-o/--output <file> ... one or more output files. Filename extensions determine output file format. Available are .gltf, .obj, .pov and .png files.
--resolution <horiz_res>,<vert_res> size in pixels for resolution-dependent outputs (.png)

Camera

Defining a camera and projection for viewing the generated scene is required for .png output. It is optional (but recommended) for .pov files. You can either use orthographic or perspective projection. The available parameters for defining the camera depend on this choice.

Orthographic view:

--oview.angle <angle_deg> downwards angle of orthographic view in degrees; defaults to 30. Only works for angles > 0° and < 90°.
--oview.from <N/E/S/W> cardinal direction from which the orthographic view is rendered; defaults to south (S)
there are two alternatives for defining the bounds of the rectangle (in the elevation=0 plane) that is projected onto the viewing plane:
- --oview.bbox <lat>,<lon> <lat>,<lon> ... list of coordinates; the closest bounds containing all these coordinates will be used
- --oview.tiles <zoom>,<tileX>,<tileY> ... one or more tiles (defined using zoom level and x/y coordinate); the closest bounds containing all these tiles will be used

Perspective view:

--pview.pos <lat>,<lon>,<ele> camera position for perspective view
--pview.lookAt <lat>,<lon>,<ele> look-at for perspective view
--pview.aspect <value> aspect ratio (width / height) for perspective view; defaults to aspect ratio of resolution
--pview.fovy <angle_deg> vertical field of view angle for perspective view, in degrees; defaults to 45.

Logging

--performancePrint prints execution times to the command line after each phase of conversion
--performanceTable <file> appends execution times to a file after the conversion, formatted as a line of a plaintext table

Other parameters

Example for alternative color scheme using the --config parameter

--config <file> properties file with additional parameters (see OSM2World/Configuration file). Can be used for both the graphical and command line interfaces.
--gui starts the #Graphical interface
--help prints a short description of the available command line parameters
--version prints the current version of OSM2World

If you use --gui, --help or --version, OSM2World will not perform a conversion - it will execute this single action instead.

Parameter files

--parameterFile <file> a file containing one set of parameters per line.

If you want to perform multiple conversions, you can write the parameters (without program name) into a file and pass it as an argument to OSM2World. Lines starting with # will be ignored.

The main advantage is that conversions will be grouped if possible - i.e. if they have the same --input and --config parameters. For example, you can quickly render the same data from different perspectives.

Examples

 ./osm2world -i example.osm -o image.png --pview.pos +50.2607,+10.965,+110.0 --pview.lookAt 50.2623367,10.9640632,0

Writes an OpenGL rendering of the 3D model generated from example.osm to image.png. The rendering uses a perspective projection, with the defined coordinates for camera position and look at.

 ./osm2world -i example.osm -o tileexample.pov

Creates a 3D model from example.osm and exports it to the POVRay file example.pov. The POVRay file will not contain a camera definition, so you have to set it manually before feeding example.pov to POVRay.

 ./osm2world -i example.osm -o tileexample.pov --oview.tiles 12,2186,1312 12,2186,1313

Creates a 3D model from example.osm and exports it to the POVRay file tileexample.pov. The POVRay file will also contain the necessary camera definition for an orthographic view. It will be chosen to show the smallest possible bounding box that includes the two tiles 2186,1312 and 2186,1313 (both zoom 12). The camera looks at that area from the south. No --oview.angle parameter is given, so it defaults to 30 degrees. This angle is particularly interesting as it means that two "normal" square tiles will fit exactly into one square orthographic tile (that's because sin(30°)=0.5).

Library interface

You can use OSM2World as a Java library. The preferred way to do this is by using the ConversionFacade class that wraps the whole conversion into a single method call. It lets you provide input data and set output targets. You can also choose which kinds of world objects you want to be created and provide fine-tuning parameters - or you can just stick to the defaults, of course. Have a look at the javadoc.

If you need more functionality, don't understand the code, etc., just ask!

Plans and limitations

OSM2World rendering featured on the front page in November 2011

Elevation data

Elevation calculation in OSM2World is currently very fragile and deactivated by default, but exists as an experimental option. The calculation is intended to use object attributes (such as incline=*, layer=*, tunnel=* and bridge=*) and absolute elevation (ele=*, either from OSM itself or converted from sources such as SRTM or OpenDEM).

Troubleshooting

It's recommended to load only small maps, especially using the graphical interface.
If OSM2World runs out of RAM, you can edit the start scripts and raise the -Xmx parameter.
If you have any other questions, ask a question on the OSM community forum or use one of the other contact options.