Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
- OpenStreetMap import from the server
- OpenStreetMap Import from a local file
- Terrain import
- Import Settings
- Roads and Paths
- Tips and Tricks
- Links and Contacts
blender-osm is an addon for Blender. It provides one click download and import of OpenStreetMap and terrain data with global coverage.
By buying the addon you support the addon development. All customers will get the addon source code under GPL license!
The following items can be imported by the addon:
- Buildings. Building height and number of floors are used to create the final scene. Composition into 3D parts for a building with the complex structure is also processed. A large number of roof shapes is supported: flat, gabled, hipped (for a quadrangle outline only), mono-pitched, half-hipped, round, pyramidal, gambrel, dome, onion and saltbox. If a terrain is provided, buildings are placed on the terrain automatically.
- Water objects (rivers and lakes). Imported as polygons. Coastlines for seas and oceans are importes as edges. If a terrain is provided, polygons for water objects are projected on the terrain.
- Vegetation areas (forests, grass, scrubs). Imported as polygons. If a terrain is provided, polygons for vegetation areas are projected on the terrain.
- Imported roads, paths and railways have width. They are represented by Blender curves with a profile object.
- Terrain. blender-osm downloads and imports real world terrain data with global coverage and the resolution about 30 meter. More information.
Polygons with holes are supported!
The addon requires at least Blender 2.76, but it makes sense to use the latest version of Blender.
Buy the addon for just $5.90. You will get a zip archive with the name blender-osm.zip. Do not unpack it! If you are on Mac and it unpacked the file automatically, compress the folder back to blender-osm.zip.
Install the addon via the usual Blender way:
- Delete the previous version of the addon if you have one:
- File → User Preferences... → Addons
- Type osm in the search box in the top left corner of the Addons tab to find the addon
- Press Remove button in the GUI box with the header Import-Export: Import OpenStreetMap (.osm)
- File → User Preferences... → Addons → Install from File...
- Find the file blender-osm.zip in your file system and press Install from File... button
- Enable the addon by checking the Enable an addon
- Set a directory to store downloaded OpenStreetMap and terrain files by pressing the button . It makes sense to create a special directory for that. It's strongly recommended to uncheck the option Relative Path in the file dialog when setting that directory as shown here.
- Press Save User Settings in the Blender User Preferences window
- Perform a quick test of blender-osm. The addon GUI is located on the
osmtab of the left side panel of the Blender 3D View (see the image below). The panel is also known as Tool shelf and toggled with the
Tkey. Simply press the button import . In a few seconds the Moscow Kremlin should appear in Blender. It is a good example of well mapped area in 3D.
- An important note for users of the Blender 2.80 Beta. The addon GUI is located on the
osmtab of the right side panel of the Blender 3D View. The panel is toggled with the
OpenStreetMap import from the server
- Press the button select to select a map extent for your area of interest. A browser window pops up with the special page to select the map extent. Follow the instructions on the webpage. At the end of this step you will have a string with coordinates copied to the clipboard. Now return back to Blender.
- Press the button paste to paste the coordinates of your area of interest.
- If you want to place OpenStreetMap buildings and other objects on the terrain, download and import the terrain first by setting the value of the drop-down list to terrain. Further details about terrain download and import can be found here. At the end of terrain import a Blender object for the terrain will be set automatically in the field . You can also set a Blender object for the terrain imported before. Actually an arbitrary Blender MESH object can be set as a terrain in the field . Leave that field blank to place all imported OpenStreetMap objects on the zero level.
- blender-osm comes with reasonable default settings. However you might want to tweak some of them as described in Import Settings
- Optional: toggle Blender System Console to track the progress of download and import of OpenStreetMap (Window → Toggle System Console).
- Press the button import to start download and import of OpenStreetMap data.
- The imported scene can be dozens of kilometers wide! It makes sence to set the far clipping distance of the 3D View at least to 10 thousand! The setting is located on the right side panel of the Blender 3D View (see the image). The panel is also known as Properties region and toggled with the
Nkey. You may also want to increase the far clipping distance of your render cameras.
- Enjoy the imported scene!
OpenStreetMap import from a local file
- Important! Do not forget to set a directory in the addon preferences to store downloaded OpenStreetMap and terrain files as described in the installation instructions. The directory is set in the field on the image above.
- Set the value of the drop-down list to file (see the image above).
- Select an OpenStreetMap file on your local disk by pressing the button as shown on the image below:
- The rest of the steps is the same as for the OpenStreetMap import from the server. Note that the GUI for selecting a map extent is not shown since the map extent is defined by your OpenStreetMap file.
- Set the value of the drop-down list to terrain (see the image above).
- Select a map extent for your area of interest as described at the beginning of OpenStreetMap import from the server. If the map extent was set before, you can skip this step.
- Optional: toggle Blender System Console to track the progress of download and import of the terrain (Window → Toggle System Console).
- Press the button import to start download and import of the terrain.
- The imported terrain can be dozens of kilometers wide! It makes sence to set the far clipping distance of the 3D View at least to 10 thousand! The setting is located on the right side panel of the Blender 3D View (see the image). The panel is also known as Properties region and toggled with the
Nkey. You may also want to increase the far clipping distance of your render cameras.
- You may want to edit the mesh of the imported terrain in the Blender EDIT or SCULPT modes. In the EDIT mode you may find useful proportional editing.
- Now you can set the value of the drop-down list to OpenStreetMap and import OpenStreetMap from the server or from a local file.
The addon comes with reasonable default settings. However you might want to tweak some of them.
Set a Blender object serving as a terrain to place OpenStreetMap buildings and other objects on the terrain. blender-osm can download and import terrain data with global coverage and the resolution about 30 meter (more information). An arbitrary Blender MESH object can serve as a terrain. Leave the field blank to place all imported OpenStreetMap objects on the zero level.
The next setting sets the mode of operation: either 3D or 2D. In the 2D mode buildings are imported as flat polygons.
The next group of settings defines which items will be imported.
If checked import buildings. The addon follows OSM Simple 3D buildings specification in the 3D mode. If a Blender object for the terrain is set, buildings will be placed on the terrain.
The settings Import water objects, Import forests, Import other vegetation, Import roads and paths, Import railways share some common properties. The related OpenStreetMap objects are imported as flat polygons or edges. If a Blender object for the terrain is set, polygons and edges for the OSM objects are cut by means of the BOOLEAN modifier to be within the limits of the terrain. A special Blender object with the suffix _envelope in its name (e.g. Terrain_envelope) is created. The object serves as bounding envelope for the terrain. Also, if a Blender object for the terrain is set, polygons and edges for the OSM objects are projected on the terrain by means of the Blender SHRINKWRAP modifier. You may want to increase the parameter Offset of the SHRINKWRAP modifier to prevent hiding of OSM polygons and edges by the terrain mesh. By default polygons and edges for the OSM objects are also sliced along the global axes X and Y to project them on the terrain correctly. See also the description of the settings Slice flat layers and Slice size below.
Import water objects
If checked import water objects (rivers and lakes) as polygons and coastlines for seas and oceans as edges. You will need to create one or more faces manually for the seas and oceans limited by the edges representing those coastlines. Obviously you can skip this step, if your OpenStreetMap data do not contain any coastline.
If checked import forests and woods as polygons.
Import other vegetation
If checked import other vegetation (grass, meadow, scrub) as polygons.
Import roads and paths
If checked import roads and paths as Blender curves with a profile object. Please refer to the section Roads and Paths how to edit the width of a specific road type.
If checked import railways as Blender curves with a profile object. Please refer to the section Roads and Paths how to edit the railway width.
Default roof shape
The setting defines a roof shape to use if the roof shape is not set in the OSM file. The default roof shape is flat. It makes sense to set the default roof shape to gabled for a village, which is a reasonable assumption for many villages in the world.
The setting defines the average level height in meters. It is used by the addon if the building height is defined by the number of levels (i.e. not by the total height in meters). The addon randomizes the level height around the given average level height.
Default number of levels
The default number of levels is assigned to an imported building if the building height (either in meters or in the number of levels) is not set for the building in the OSM file. To achieve realism you can add several default numbers of levels with their relative weights between 1 and 100. Use the buttons
- to add or delete an entry for the default number of levels. On the screenshot above the default number of levels 5 has the relative weight 40, while the default number of levels 4 has the relative weight 10. It means that a building will get 5 levels 4 times more often than 4 levels.
Import as a single object
Imported objects are arranged into layers. Those layers (further referred to as addon layers) are not to be confused with Blender layers! The addon layers are defined by the settings mentioned above: buildings, roads and paths, railways, water, forests, vegetation.
☑ Import as a single object checked
This is the default state of the settings.
OSM elements belonging to a specific addon layer are imported as the single Blender object, so a separate Blender object is created only for each addon layer (not for each OSM element).
☐ Import as a single object unchecked
An OSM element is imported as a separate Blender object and parented to a Blender EMPTY object representing the related addon layer. A complex building composed of several parts is imported as a single Blender object in the 3D mode. Only the building outline is imported for that complex building in the 2D mode.
All OSM tags of each imported OSM element are set as Blender custom properties for the related Blender object:
If a Blender object for the terrain is set, the setting Import as a single object is assumed to be checked for the flat addon layers (water, forests, vegetation, roads, railways), but the actual value of that setting is still taken into account for buildings.
Ignore existing georeferencing
If checked, existing georeferencing for the Blender scene is ignored. A Blender scene is called georeferenced if it has custom properties lat and lon. The geographical coordinates lat and lon correspond to the the origin of the Blender global coordinate system. OpenStreetMap and terrain data are imported with respect to those geographical latitude and longitude if the setting is unchecked. blender-osm sets custom properties lat and lon for the Blender scene if the scene does not have them or if the setting is checked.
Slice flat layers
The settings are available only if a Blender object for the terrain is set. If the setting Slice flat layers is checked, the flat addon layers (water, forests, vegetation, roads, railways) are sliced along the global axes X and Y to project them on the terrain correctly. The setting Slice size defines the slice size along both axes X and Y.
Roads and Paths
Roads and paths are imported as Blender curves with a profile object.
The profile objects for the roads and paths are located in the second Blender layer. A specific profile object is set for each type of a road or path. The width of the specific road type can be adjusted by editing the related profile object in the following way:
- Select the Blender curve representing the desired road type.
- Go to the curve settings in the properties window to see the name of the Blender object for the curve profile. It's set in the GUI field Bevel Object:
Shift 2to see both the imported OpenStreetMap scene and the roads profiles. The latter are located in the close vicinity of the origin of the Blender coordinate system.
- Select the related road profile and press
Tabto start editing it the EDIT mode.
- Perform scaling of the profle vertices or simply move them. The corresponding road or path will change interactively as you edit its profile.
Tabagain to finish editing the road profile.
To convert Blender curves to mesh, select the desired curves press
Alt C and select Mesh from Curve/Meta/Surf/Text in the popup menu.
Tips and Tricks
Set far clipping distance of the 3D View and your render cameras at least to 10 thousand! The imported scene can be dozens of kilometers wide!
Take care with large .osm files (hundreds of megabytes and more)! For example, an OSM file used to create the scene of New York center shown on the very top image had the size of 350 Mb. It contained more than 100.000 buildings. It took about 1 hour to import the file. Even larger .osm files may hang up your computer completely.
Color and physical material for the walls and the roof aren't set for each building in an OSM file. If they are missing, the addon applies the default Blender materials for the walls and the roof. Those default Blender materials have the names wall and roof respectively.
You can edit the Blender materials wall and roof or replace them with your own.
Custom map projections
To use a custom map projection defined by a SRID (e.g. EPSG:3857) or by PROJ.4 parameters (e.g. +proj=tmerc +a=6378137 +b=6378137 +lat_0=55.752 +lon_0=37.618 +k_0=1 +x_0=0 +y_0=0 +units=m) install and activate the bpyproj addon. Extra GUI fields will appear at the bottom part of the blender-osm GUI panel. To return the default blender-osm projection simply deactivate the bpyproj addon. See the bpyproj documentation for additional details.
- Hipped roofs are supported only for a quadrangle building outline
- Only simple diffuse materials are applied to the imported objects at the moment.