Importing from OpenStreetMap

Where the importer lives

Three buttons open the same window. On the START screen of a new project it is Download OSM, sharing the bottom edge of the green Start with default block with Draw road. In Roads mode with no roads yet, the empty state offers Draw Road and Import OSM. In Graph mode (Alt+1), while no mesh is assigned as the base graph, the rail carries an OSM card whose first button is Download OSM.

All three run the operator icity2.open_osm_import, which opens the window over the main 3D viewport rather than inside the editor area you clicked in. Its title bar reads IMPORT OSM.

The import does not need a Parametra account. Nothing in the import path sends an Authorization header or contacts Parametra: the map tiles, the street data, the satellite imagery and the optional terrain heights all come from public third-party services. It spends no credits and creates no cloud job. Creating a project to import into works signed out as well, because the project folder is written to disk first and registration with Parametra is a separate step that reports its own failure.

The IMPORT OSM window

The window is a map, with coordinate fields above it and an Import button below. It opens centred on Cairo (30.0444, 31.2357) at zoom 12 until you move it. A red crosshair marks the centre of the view.

1. Type a Latitude and Longitude, set Zoom (2–18), and press Go to. Or navigate directly: scroll to zoom, middle-drag to pan. The fields follow the map as you move it, and a place name for the centre appears beside the coordinates a moment after you stop.
2. Left-drag a box over the area you want. Inside the box stays bright and outside dims, and the readout under the map changes from No region selected to the ground size of the box, in metres or kilometres. Clear removes the box.
3. Press Import. The window closes and the import starts. With no box drawn, Import takes the whole visible map area instead.

The line under the map is attribution, not decoration. The basemap is the terrestris free OSM-WMS service and the data is OpenStreetMap; both require that credit, which is why it reads © OpenStreetMap contributors · terrestris.

How large an area you can take

Before anything downloads, the request is checked. If it fails the check, the first problem appears in the iCity Logs editor and nothing runs.

These are backstops, not targets. Street data is fetched from Overpass in 4 km tiles across three public mirrors, and every stage after it costs more than linearly in the number of ways, so a box near the limit is a long import rather than a fast one. Start smaller than you think you want.

What the import brings in

The import runs three stages in order, and the engine is started for you if it is not already running. It comes up without building a default city, so you get the imported streets and nothing else.

• —Downloading OpenStreetMap data — the network half runs off the main thread, so Blender stays usable. It asks Overpass for buildings, highways, railways, water, landuse, parks and a handful of tagged points, then builds two meshes in the scene: OSM_Roads and OSM_Buildings.
• —Generating roads, blocks and buildings — two engine passes. The first turns the road network into roads, sidewalks, junction nodes and blocks. The second extrudes the building footprints and parents them to those blocks.
• —Projecting satellite imagery — a Sentinel-2 cloudless raster for the same box, UV-mapped onto the blocks as a material named MAT_OSM_Satellite. This stage is decorative: if the imagery fails to download, the import still succeeds.

Terrain height is off by default. Turn on OSM: sample terrain elevation in Edit → Preferences → Add-ons → iCity 2 and roads ramp with the ground instead of lying flat. It samples a 40 by 40 grid of SRTM 30 m points, which adds about twenty seconds to the first import of an area; those samples are cached for a week, so repeats are free. The setting lives in preferences, not in the window.

Watching it, and stopping it

There is no progress bar. The window closes when you press Import, and the only running commentary is in the iCity Logs editor, where every line is prefixed OSM: — the import starting, each stage beginning by name, and a final line carrying the elapsed time and the counts, or the failure and its suggested remedy.

Blender stays responsive throughout, and only one import can run at a time. iCity undo is blocked for the duration, on purpose, so that a Ctrl+Z in the middle cannot rewind into a half-imported city. It is released when the import ends, however it ends.

To stop an import, press F3 and run Cancel OSM Import. That operator has no button in any panel, so search is the only way to it. The engine stage has a two-hour ceiling before it is declared hung, which is deliberately generous: a large box genuinely takes a long time, and a stuck engine looks the same as a slow one until that ceiling is reached.

Everything the job wrote is left on disk, under %TEMP%\icity2_gis\ in a folder named for the job, one file per stage.

request.json   the box and options, exactly as accepted
frame.json     the projection frame
osm.json       what came back from Overpass
scene.json     the objects the build made
engine.json    what was dispatched, and what returned
imagery.png    the satellite raster
project.json   what the imagery was painted onto
result.json    the whole job's outcome

If you need to report a failed import, that folder is the thing to send.

What to expect, honestly

This path is wired end to end and it is not finished. Read this section before you build a project around it.

• —It is lightly tested. Two comments in the source still describe the window as a prototype with the import “wired later”. Those comments are stale — the button really does start a real import — but the path has had far less use than drawing roads by hand. Treat a first import as an experiment.
• —Most of the OSM card does nothing yet. In the Graph rail, only Download OSM is connected. Merge points by distance, Straighten segments by angle, Clean OSM and Convert to iCity Geometry are interface with no algorithm behind them: the two sliders remember their values and the two buttons print a note to the console. The slider tooltips say so.
• —The services are keyless and third-party. The basemap is terrestris, the place names come from komoot's Photon, the street data from public Overpass mirrors, the imagery from EOx. All are fair-use endpoints with no contract behind them, so a slow or unavailable one is a normal outcome rather than a fault in your install. The EOx satellite mosaic is licensed non-commercial and share-alike, and the import bakes it into your scene.
• —Imported roads edit differently. You can move junction nodes, change a road's width and draw new roads onto the network; each of those re-runs the road pass over the whole imported network. Subdivide and delete are refused on OSM roads and report why, because they work from base-graph edges that an imported network does not have. Lane edits are refused on OSM roads too.

If nothing happened

The question this page exists to answer: when an import produces nothing, is it you, your sign-in, or the feature? It is never your sign-in. Open the iCity Logs editor and match what it says.

A grey map inside the window is the same certificate story as the sixth row, one step earlier: the tiles come over the same transport the import uses. If the map draws, the import's network path is working.

For anything not listed here, see Troubleshooting; for what the engine is doing while the second stage runs, see The engine; and for editing what you have imported, see Roads and junctions.