Using OSM2World as a library on the JVM

Dependencies

OSM2World requires Java 17 or higher. Include the following repository and dependency through Maven or Gradle:

Maven

Gradle

    <repositories>
        <repository>
            <id>jitpack.io</id>
            <url>https://jitpack.io</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>com.github.tordanik.OSM2World</groupId>
            <artifactId>osm2world-core</artifactId>
            <version>3be7059</version>
        </dependency>
    </dependencies>

repositories {
    mavenCentral()
    maven {
        url = uri("https://jitpack.io")
    }
    maven {
        url = uri("https://mvn.topobyte.de")
    }
    maven {
        url = uri("https://mvn.slimjars.com")
    }
}

dependencies {
    implementation("com.github.tordanik.OSM2World:osm2world-core:3be7059")
}

The osm2world-core package is required. You may additionally depend on osm2world-opengl if you want to use OpenGL for real-time graphics or image rendering.

Example: Creating and exporting a simple model

In this example, we’re exporting to binary glTF (.glb):

Java

Kotlin

import org.osm2world.O2WConverter;
import org.osm2world.map_data.creation.MapDataBuilder;
import org.osm2world.map_data.data.TagSet;
import org.osm2world.output.gltf.GltfOutput;

import java.io.*;
import java.util.List;

void main() throws IOException {

    var o2w = new O2WConverter();

    var builder = new MapDataBuilder();

    var tags = TagSet.of(
            "building", "yes",
            "building:levels", "5",
            "roof:levels", "2",
            "roof:shape", "hipped"
    );

    // coordinates are in meters
    var wayNodes = List.of(
            builder.createNode(0.0, 0.0),
            builder.createNode(15.0, 0.0),
            builder.createNode(15.0, 10.0),
            builder.createNode(0.0, 10.0)
    );

    builder.createWayArea(wayNodes, tags);

    o2w.convert(builder.build(), null, new GltfOutput(new File("output.glb")));

}

import org.osm2world.O2WConverter
import org.osm2world.map_data.creation.MapDataBuilder
import org.osm2world.map_data.data.TagSet
import org.osm2world.output.gltf.GltfOutput
import java.io.File

fun main() {

    val o2w = O2WConverter()

    val builder = MapDataBuilder()

    val tags = TagSet.of(
        "building", "yes",
        "building:levels", "5",
        "roof:levels", "2",
        "roof:shape", "hipped"
    )

    // coordinates are in meters
    val wayNodes = listOf(
        builder.createNode(0.0, 0.0),
        builder.createNode(15.0, 0.0),
        builder.createNode(15.0, 10.0),
        builder.createNode(0.0, 10.0)
    )

    builder.createWayArea(wayNodes, tags)

    o2w.convert(builder.build(), null, GltfOutput(File("output.glb")))

}

Loading config options, textures and models

For most use cases, we want the resulting 3D scene to have textures and make use of external models. This requires a configuration with styling options.

You can download the default visual style for OSM2World from the OSM2World-default-style repository. Once you have placed the contents it in a location where your application can access it, you can modify the initial example like this:

Java

Kotlin

    var o2w = new O2WConverter();
    o2w.setConfig(new O2WConfig(Map.of( /* extra options go here */ ), new File("standard.properties")));

    ...

    val o2w = O2WConverter()
    o2w.setConfig(O2WConfig(mapOf( /* extra options go here */ ), File("standard.properties")))

    ...

O2WConfig has fields with associated documentation for some of the config options available for OSM2World.

Loading OSM data from a file or database

With the example above, we create the input data with a MapDataBuilder. Often we want to load data in the OpenStreetMap data format from an existing file or database instead. For this purpose, OSM2World offers several OSMDataReaders for typical data sources:

OSMFileReader and OSMStreamReader for reading from .osm.pbf or OSM .xml files (including the JOSM dialect)
GeodeskReader for reading from a GeoDesk .gol file
MbtilesReader for reading .osm.pbf tiles stored inside an .mbtiles SQLite database
OverpassReader for reading from an Overpass API instance

Exporting to other output formats

OSM2World offers other output formats besides GltfOutput. These include:

ObjOutput
ImageOutput (requires osm2world-opengl in addition to osm2world-core)
JoglOutput (requires osm2world-opengl in addition to osm2world-core)

Other more specialized Output implementations are available as well.

Working with meshes generated by OSM2World

If you would like to directly process the meshes generated by OSM2World, rather than using an Output implementation, you can use the Scene object returned by O2WConverter.convert as your starting point. (Make sure to filter Meshes by LOD if you haven’t set a single LOD through a config option.)