Your first 3D map.

1. Open the notebook in Colab

Sign in to Google, connect a runtime, and run the setup cell first. It downloads the repository and installs the package. Then run the examples in order; each map appears below its cell.

The notebook includes the sample GeoJSON data. Trees and shadows are covered in examples 5 and 6; the final example combines all visual modules.

2. Install locally

Use Python 3.10 or newer. Run these commands in a terminal. On Windows, use .venv\Scripts\activate instead of the activation command below.

git clone https://github.com/yfeng-hsm/Basemap3D.git
cd Basemap3D
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[notebook]"
python -m jupyterlab

Open notebooks/Mainz_Modules.ipynb in JupyterLab and select the Python environment you installed above. Keep the repository as your working folder so relative data paths work.

3. Create a map, then add modules

In a notebook cell, start with Map. Terrain and 3D buildings are included. Add imagery, polygons, trees or shadows with .add_to(m). Finish the cell with m to display it.

from basemap3d import Map, WmsTileLayer, TreeLayer

m = Map(location=[49.99892, 8.27412], distance_m=450)
WmsTileLayer(opacity=0.7).add_to(m)
TreeLayer().add_to(m)
m

TreeLayer provides estimated trees for the Mainz study area. For your own polygons, add GeoJson before NearbyBuildings. See Examples for complete combinations.

4. Save and open a webpage

Export the scene from your notebook or Python script:

m.save("results/map.html")

From the repository folder, start a local web server:

python -m http.server 8000

Open http://localhost:8000/results/map.html in your browser. VS Code Live Server / Go Live also works. Keep the server running while viewing the map; online map services are still required.

In Colab, view maps directly below the notebook cells. Download a saved HTML file if you want to host or share it later.