### Install requests library

Source: https://github.com/vvoovv/blosm/wiki/Fixing-touching-OpenStreetMap-polygons

Install the 'requests' library using pip. This is a prerequisite for running the provided Python scripts.

```bash
pip install requests
```

--------------------------------

### Install Blosm Addon in Blender

Source: https://context7.com/vvoovv/blosm/llms.txt

Follow these UI-based steps to install the Blosm addon in Blender. Ensure the data directory is set correctly, and optionally configure the asset pack directory for the Pro version. API keys for satellite imagery can also be entered here.

```plaintext
# Blender installation steps (UI-based, no Python scripting required):
# 1. Edit → Preferences → Add-ons → Install...
# 2. Select blosm_2.7.22.zip  (do NOT unpack the zip first)
# 3. Enable the addon by checking "Enable Add-on"
# 4. Set the data directory (for cached OSM/terrain files):
#    Edit → Preferences → Add-ons → Blosm → [folder icon]
#    Recommendation: uncheck "Relative Path" in the file dialog

# Pro version only — also set the asset pack directory:
#    Edit → Preferences → Add-ons → Blosm → [asset pack folder icon]
#    Point to the folder containing building_materials.blend and vegetation.blend

# Optional API keys (entered in addon preferences):
#   ArcGIS access token  — for ArcGIS satellite imagery
#   Mapbox access token  — for Mapbox satellite/streets imagery
#   Google 3D Tiles Key  — for Google photorealistic 3D cities
```

--------------------------------

### Import OpenStreetMap from Local File

Source: https://context7.com/vvoovv/blosm/llms.txt

This describes how to import OpenStreetMap data from a local `.osm` file. It includes an example Overpass query for downloading city data and instructions for setting the file path in the Blosm addon preferences within Blender. The map extent is automatically derived from the file.

```plaintext
# Download OSM data for a city within its administrative boundaries
# using the Overpass API (example: Montreal, relation id 8508277)

# Overpass query — paste at http://overpass-turbo.eu
[out:xml];
(
  node(area:3608508277);   # 3600000000 + relation_id
  <;
);
out;

# Export: Export → Data → raw data directly from Overpass API → done
# Save file with .osm extension

# Blender UI — Blosm tab:
#   Set drop-down to "file"
#   Press [file selector button] → navigate to your .osm file
#   The map extent is automatically derived from the file
#   Configure import settings as for server import (see above)
#   Press [import]
```

--------------------------------

### Geometry Nodes on Building Footprints (2D Mode)

Source: https://context7.com/vvoovv/blosm/llms.txt

Applies a Geometry Nodes modifier to 2D building footprint polygons to procedurally generate 3D building geometry. Requires Blosm addon version ≥ 2.6.0 and a specific Geometry Nodes setup file.

```text
# Requirements:
#   Blosm addon version ≥ 2.6.0
#   Geometry Nodes setup file (available free at gumroad.com — search "Pavel Oliva blosm")

# Blender UI — Blosm tab:
#   Set Mode to "2D"  (toggle button in addon panel)
#   Select a small area (a few hundred meters wide for viewport performance)
#   Set "Geometry Nodes file" field → path to downloaded .blend with GN setup
#   Set "Geometry Nodes setup name" → "building"  (must be exactly "building")
```

--------------------------------

### Overpass API Query with City Boundary ID

Source: https://github.com/vvoovv/blosm/wiki/OpenStreetMap-data-limited-by-city-boundaries

This example demonstrates how to construct an Overpass API query by incorporating a specific city's boundary ID. The 'area:' parameter is used to specify the geographic region.

```overpassql
[out:xml];
(
  node(area:3608508277);
  <;
);
out;
```

--------------------------------

### Import OpenStreetMap from Server

Source: https://context7.com/vvoovv/blosm/llms.txt

This outlines the UI workflow for downloading and importing OpenStreetMap data (buildings, roads, water, forests, vegetation) for a selected bounding box directly from servers. It includes steps for selecting the map extent, pasting coordinates, optionally importing terrain, configuring import settings, and monitoring progress. Adjust the 3D View far clipping distance for large scenes.

```plaintext
# Blender UI workflow — Blosm tab → N panel → 3D View

# Step 1: Select map extent
#   Press [select] button → browser opens a map extent selector
#   Draw your area of interest → coordinates are copied to clipboard

# Step 2: Paste coordinates back into Blender
#   Press [paste] button in the Blosm panel

# Step 3: (Optional) Import terrain first so buildings snap to it
#   Set drop-down to "terrain" → press [import]
#   After terrain import, the terrain object is auto-set in the Terrain field

# Step 4: Configure import settings (defaults are reasonable)
#   Mode:                3D  (or 2D for flat footprints)
#   Import buildings:    ✓
#   Import water:        ✓
#   Import forests:      ✓
#   Import roads/paths:  ✓   (imported as Blender curves with profile bevel)
#   Import railways:     ✓
#   Default roof shape:  flat (or "gabled" for villages)
#   Level height:        3.0 m (average floor-to-floor height)

# Step 5: Press [import]
#   Monitor progress: Window → Toggle System Console

# Post-import tip — large scenes can be dozens of km wide:
#   Set 3D View far clipping distance to ≥ 10,000
#   (N panel → View → Clip End: 10000 m)

# Supported roof shapes (read from OSM roof:shape tag automatically):
#   flat | gabled | hipped | mono-pitched | half-hipped
#   round | pyramidal | gambrel | dome | onion | saltbox
```

--------------------------------

### Import Forests and Trees (Pro Version)

Source: https://context7.com/vvoovv/blosm/llms.txt

In the Blosm tab (Pro version, 3D realistic mode), enable 'Import forests and separate trees' and set the 'Number of trees per hectare'. Trees are planted on terrain if available, otherwise a flat terrain is created.

```text
# Blender UI — Blosm tab (Pro, 3D realistic mode):
#   Check "Import forests and separate trees" option
#   Set "Number of trees per hectare" (default: varies; reduce for large forests)
#     1 hectare = 10,000 m² (100m × 100m plot)
#     Large forests can have millions of trees — reduce density significantly
#   If terrain is set → trees are planted on the terrain surface
#   If no terrain → addon creates a flat terrain for tree placement
#   Press [import]
```

--------------------------------

### Import Google 3D Tiles in Blender

Source: https://context7.com/vvoovv/blosm/llms.txt

Follow these steps to import Google 3D Tiles data using the Blosm add-on. Ensure 'Viewport Shading' is set to 'Material Preview' or 'Rendered' for best results. Joining objects and using relative import are recommended settings.

```plaintext
# Blender UI — Blosm tab:
#   Set drop-down to "3D Tiles"
#   Set Source = "Google"
#   Press [select] → choose map extent in browser → press [paste]
#   Choose level of detail (start small!):
#     "groups of buildings"   — lowest detail, fastest
#     "separate buildings"    — medium
#     "buildings with details"— highest detail, slowest / most triangles
#   Set Viewport Shading to "Material Preview" or "Rendered"
#   Press [import]

# Import settings:
#   Join 3D Tiles objects:      ✓  (merges tiles into one mesh, removes doubles)
#   Relative to initial import: ✓  (subsequent imports align to first import origin)
```

--------------------------------

### Import Satellite Imagery / Web Map Overlays in Blender

Source: https://context7.com/vvoovv/blosm/llms.txt

Downloads and projects tiled web map imagery onto a terrain mesh or a flat plane. Requires an access token for services like ArcGIS or Mapbox, but OSM Mapnik is free.

```plaintext
# Blender UI — Blosm tab:
#   Set drop-down to "image overlay"
#   Set Terrain field if projecting onto existing terrain (auto-set after terrain import)
#   Select overlay type:
#     "ArcGIS Satellite"  — requires ArcGIS access token
#     "Mapbox Satellite"  — requires Mapbox access token
#     "OSM Mapnik"        — free, no token needed
#     "Mapbox Streets"    — requires Mapbox access token
#     "Custom URL"        — any XYZ tile server or Mapbox style
```

--------------------------------

### Import Google 3D Cities Prerequisites

Source: https://context7.com/vvoovv/blosm/llms.txt

This section lists the prerequisites for importing Google's photorealistic 3D city mesh using the Google Maps Tiles API. It requires enabling the Maps Tiles API in the Google Cloud Console and setting up a billing account, as API usage beyond the free tier incurs costs.

```plaintext
# Prerequisites:
#   1. Enable Maps Tiles API in Google Cloud Console
#   2. Create a billing account (required for API key; first 1000 imports/month are free)
```

--------------------------------

### Import Custom 3D Tiles from URL in Blender

Source: https://context7.com/vvoovv/blosm/llms.txt

Import city-scale 3D mesh models from any OGC 3D Tiles-compliant public dataset using a root URL. Adjust the 'Geometric error' setting to control detail and performance.

```plaintext
# Example: import Helsinki 3D city model
# Root URL: https://kartta.hel.fi/3d/b3dm_2017_2/tileset.json

# Blender UI — Blosm tab:
#   Set drop-down to "3D Tiles"
#   Set Source = "Custom"
#   Press [select] → choose map extent within Helsinki → press [paste]
#   Paste Root URL: https://kartta.hel.fi/3d/b3dm_2017_2/tileset.json
#   Set Geometric error (default: 30 — lower = more detail, slower):
#     30  → reasonable detail, fast
#     15  → higher detail
#     5   → very high detail, potentially very slow
#   Press [import]
```

--------------------------------

### Enable Experimental Export Features

Source: https://context7.com/vvoovv/blosm/llms.txt

To enable experimental export features for scene export, go to Edit → Preferences → Add-ons → Blosm and check 'Enable experimental features'.

```text
# Enable experimental export features:
#   Edit → Preferences → Add-ons → Blosm
#   Check "Enable experimental features" at the bottom of preferences
```

--------------------------------

### Bake Textures for Export (Pro Version)

Source: https://context7.com/vvoovv/blosm/llms.txt

For the Pro version, this process bakes all textures into a single image, which is necessary for certain export formats like FBX/OBJ. For glTF, no extra steps are needed after baking.

```plaintext
# Pro version only — Bake all textures into a single image:
#   Select 3D Tiles object(s) → Tools section → set texture size → press [Bake]
#   For glTF: no extra steps needed after baking
#   For FBX/OBJ: open Image Editor → find "ObjectName Bake Emit" image
#                → Shift+Alt+S → save next to .blend file
```

--------------------------------

### Import and Initialize Transverse Mercator Projection

Source: https://github.com/vvoovv/blosm/wiki/Georeferenced-Blender-Scene

Imports the TransverseMercator module and initializes a projection object using latitude and longitude from the Blender scene's custom properties. Ensure the scene has '_lat_' and '_lon_' properties defined.

```python
from transverse_mercator import TransverseMercator

scene = bpy.context.scene
projection = TransverseMercator(lat=scene["lat"], lon=scene["lon"])
```

--------------------------------

### Summary: Detect touching inners

Source: https://github.com/vvoovv/blosm/wiki/Fixing-touching-OpenStreetMap-polygons

A quick reference command to detect touching inner polygons using the provided Python script.

```bash
python josm_select_touching_polygons.py --tag natural=wood --osm-file myarea.osm
```

--------------------------------

### Note on Import for Export Workflow

Source: https://context7.com/vvoovv/blosm/llms.txt

If 'Import for export' is unchecked, the newer addon core is used, leading to different results. The export workflow specifically requires the legacy core (import for export = checked).

```text
# Note: if "Import for export" is unchecked, the newer addon core is used for import.
#       Results will differ from the standard import. The export workflow requires
#       the legacy core (import for export = checked).
```

--------------------------------

### Enable Export-Compatible Import Mode

Source: https://context7.com/vvoovv/blosm/llms.txt

For scene export, check 'Import for export' in the Blosm panel before importing OSM data. This ensures compatibility with the legacy core required for the export workflow.

```text
# Enable export-compatible import mode:
#   In the Blosm panel, check "Import for export" before importing OSM data
#   Then import OpenStreetMap as usual
```

--------------------------------

### Importing GPX Tracks into Blender

Source: https://context7.com/vvoovv/blosm/llms.txt

Imports GPX track files as Blender curve objects. Optionally projects the track onto imported terrain, ignoring elevation data if 'Project on terrain' is checked. Requires the terrain object to be set in the Terrain field.

```text
# Blender UI — Blosm tab:
#   Set drop-down to "gpx"
#   Set path to your .gpx file in the file field
#
#   Option: "Project on terrain" ✓
#     → ignores vertical (elevation) coordinates in the GPX file
#     → projects track flat onto the terrain surface
#     → terrain object must be set in the Terrain field
#
#   Option: "Project on terrain" ✗
#     → uses elevation data embedded in the GPX file
#
#   Press [import]
#   → Track is imported as a Blender CURVE object

# Note: only GPX tracks are supported — routes and waypoints are not imported

# Typical workflow for outdoor/hiking visualization:
#   1. Import terrain (drop-down = "terrain") → press [import]
#   2. Import satellite imagery (drop-down = "image overlay") → press [import]
#   3. Import GPX track (drop-down = "gpx", check "Project on terrain") → press [import]
```

--------------------------------

### Import Real-World Terrain (DEM/SRTM) in Blender

Source: https://context7.com/vvoovv/blosm/llms.txt

Downloads and imports SRTM digital elevation model data to create a Blender mesh for terrain. Subsequent OSM or overlay imports will automatically snap to this terrain.

```plaintext
# Blender UI — Blosm tab:
#   Set drop-down to "terrain"
#   Press [select] → choose terrain extent → press [paste]
#   Press [import]
#   → Downloads .hgt SRTM files, generates a terrain mesh
#   → Terrain object is automatically set in the Terrain field
#      for subsequent OSM/overlay imports

# After terrain import:
#   Adjust far clipping distance to ≥ 10,000 m (terrain can be 10s of km wide)
#   Optionally sculpt or edit the mesh:
#     Tab → Edit Mode → use Proportional Editing (O key) for smooth reshaping
#     Or: Ctrl+Tab → Sculpt Mode

# Then import OSM on top of terrain:
#   Set drop-down back to "OpenStreetMap"
#   Terrain field will already be populated
#   Buildings auto-place on terrain surface
#   Roads/water/vegetation projected onto terrain via SHRINKWRAP modifier
```

--------------------------------

### Export Scene to Standard 3D Formats

Source: https://context7.com/vvoovv/blosm/llms.txt

Export the imported OSM scene using Blender's built-in exporters. Supported formats include FBX, Collada, OBJ, and glTF.

```text
# Export the scene:
#   File → Export → choose format:
#     FBX:      File → Export → FBX (.fbx)
#     Collada:  File → Export → Collada (.dae)
#     OBJ:      File → Export → Wavefront (.obj)
#     glTF:     File → Export → glTF 2.0 (.glb/.gltf)
```

--------------------------------

### Exporting Google 3D Tiles from Blender

Source: https://context7.com/vvoovv/blosm/llms.txt

Steps for exporting imported 3D Tiles data from Blender. This process involves replacing materials, unpacking resources, and then exporting to common formats like FBX, OBJ, or glTF. Blender 4.3.2+ is recommended.

```plaintext
# Exporting Google 3D Tiles (Blender 4.3.2+ recommended):
#   1. Select imported 3D Tiles objects
#   2. In the Tools section at bottom of panel → press [Replace Materials]
#      (converts non-exportable materials to export-ready ones)
#   3. File → External Data → Unpack Resources
#      → "Use files in current directory (create when necessary)"
#      (textures saved to ./textures/ folder)
#   4. Export via File → Export → FBX / OBJ / glTF
```

--------------------------------

### Adjust Floor Distribution in Geometry Nodes

Source: https://context7.com/vvoovv/blosm/llms.txt

After importing buildings, select a building object and navigate to the Geometry Nodes modifier to adjust the 'num_levels' input distribution.

```text
# Post-import — adjust floor distribution:
#   Select any building object → Properties → Modifier (wrench) → Geometry Nodes
#   Adjust "num_levels" input distribution inputs
```

--------------------------------

### Editing Road Width with Bevel Profiles

Source: https://context7.com/vvoovv/blosm/llms.txt

Adjusts road and path widths non-destructively by editing bevel profile objects. Profile objects are located in the 'way_profiles' collection and can be scaled or moved in Edit Mode to update road widths interactively.

```text
# Road width adjustment workflow:
#
# 1. After OSM import, profile objects are in the Blender collection "way_profiles"
#    Enable the collection in the viewport (eye icon in Outliner)
#
# 2. Select the curve object for the road type you want to adjust
#    Go to Properties → Object Data (curve icon) → Geometry → Bevel → Object
#    Note the name of the bevel object (e.g. "motorway_profile")
#
# 3. Select the profile object in "way_profiles" collection
#    Press Tab → Edit Mode
#    Scale or move vertices to adjust road width
#    → All roads of that type update interactively
#    Press Tab → exit Edit Mode
#
# 4. Convert curves to mesh if needed for export:
#    Select road curve(s) → Right-click → Convert to Mesh

# Road types with individual profiles:
#   motorway, trunk, primary, secondary, tertiary,
#   residential, service, footway, cycleway, railway, ...
```

--------------------------------

### Complete multipolygon members in JOSM layer

Source: https://github.com/vvoovv/blosm/wiki/Fixing-touching-OpenStreetMap-polygons

Run this script to download and add missing members (inner/outer ways) of tagged multipolygon relations to your current JOSM layer. Ensure JOSM remote control is enabled.

```bash
python josm_complete_multipolygon_members.py --tag natural=wood --osm-file myarea.osm
```

--------------------------------

### Detect touching polygons in JOSM layer

Source: https://github.com/vvoovv/blosm/wiki/Fixing-touching-OpenStreetMap-polygons

Execute this script to find inner rings that share nodes with other inner rings or the outer ring, and select them in JOSM. The script requires the path to your OSM file and a tag filter.

```bash
python josm_select_touching_polygons.py --tag natural=wood --osm-file /path/to/myarea.osm
```

--------------------------------

### Using Custom Tree Models for Vegetation

Source: https://context7.com/vvoovv/blosm/llms.txt

To use custom tree models, open 'vegetation.blend', import or create models, set their Y-axis rotation to 90°, and add them to the 'trees' particle group. Save the blend file.

```text
# Using custom tree models (advanced):
#   Open vegetation.blend from the asset pack
#   Import or create your tree models
#   Set Y-axis rotation to 90° for each model:
#     Properties → Object → Transform → Rotation Y = 90°
#   Add models to the "trees" particle group:
#     Select your models + "pine low poly" (Shift) → Shift+Ctrl+G → "trees"
#   Save vegetation.blend
#   Remove a model from trees group: select model → Ctrl+Alt+G → "trees"
```

--------------------------------

### Basic Overpass API Query Structure

Source: https://github.com/vvoovv/blosm/wiki/OpenStreetMap-data-limited-by-city-boundaries

This is a basic query structure for the Overpass API. Replace the area ID with the sum of '3600000000' and the city's boundary ID.

```overpassql
[out:xml];
(
  node(area:3600000000);
  <;
);
out;
```

--------------------------------

### Georeferenced Scene Coordinate Conversion

Source: https://context7.com/vvoovv/blosm/llms.txt

Enables Python-based conversion between geographic (latitude/longitude) and Blender 3D coordinates using the TransverseMercator utility. The scene object stores the geographic origin (lat, lon, heading) as custom properties.

```python
# The scene stores the geographic origin:
#   bpy.context.scene["lat"]  — latitude of Blender's world origin
#   bpy.context.scene["lon"]  — longitude of Blender's world origin
#   bpy.context.scene["heading"]  — rotation angle (optional)

# Use TransverseMercator from blosm's utility module for coordinate conversion:
from transverse_mercator import TransverseMercator
import bpy

scene = bpy.context.scene
projection = TransverseMercator(lat=scene["lat"], lon=scene["lon"])

# Convert Blender XY coordinates → geographic (lat, lon):
x, y = 1500.0, -800.0   # meters from scene origin in Blender space
lat, lon = projection.toGeographic(x, y)
print(f"Geographic: {lat:.6f}, {lon:.6f}")
# Output: Geographic: 48.856614, 2.352222  (example: near Paris center)

# Convert geographic (lat, lon) → Blender XY coordinates:
target_lat, target_lon = 48.8584, 2.2945   # Eiffel Tower
x, y = projection.fromGeographic(target_lat, target_lon)
print(f"Blender coords: x={x:.1f}, y={y:.1f}")
# Output: Blender coords: x=-4213.7, y=213.4  (meters from origin)
```

--------------------------------

### Adjust Particle Display for Viewport Performance

Source: https://context7.com/vvoovv/blosm/llms.txt

To improve viewport performance when importing forests, select the terrain, go to the Particles tab, and adjust the 'Viewport Display' amount. For rendering, use the 'Emission' panel's 'Number' setting.

```text
# Adjusting particle display in viewport (performance):
#   Select terrain → Properties → Particles tab
#   "Viewport Display" panel → Amount: set percentage (e.g. 10%)
#   "Emission" panel → Number: total tree count for rendering
```

--------------------------------

### Convert Geographic Coordinates to Blender Coordinates

Source: https://github.com/vvoovv/blosm/wiki/Georeferenced-Blender-Scene

Converts geographical latitude and longitude to Blender's global X and Y coordinates using an initialized TransverseMercator projection. This allows placing objects in the Blender scene based on real-world coordinates.

```python
(x, y) = projection.fromGeographic(lat, lon)
```