A Godot plugin for loading geospatial data. Written as a GDExtension with C++ and GDAL.
Various types of Raster and Vector data can be loaded from georeferenced files and used in Godot. One might load a heightmap from a GeoTIFF, building footprints from a Shapefile, or an entire database of data from a GeoPackage. Thanks to efficient filtering and cropping, data can be loaded in real-time.
Automated builds of the addon with an included demo can be found in the GitHub Actions tab. The master branch is a GDExtension plugin for Godot 4.x. For Godot 3.x with GDNative, use the godot3 branch and its builds.
Documentation generated via Doxygen can be found here: https://boku-ilen.github.io/geodot-plugin/
Feel free to join our Discord for talking about geospatial Godot: https://discord.gg/MhB5sG7czF
The included Godot project offers various demo scenes - we recommend looking through that code to get started. Just do give you an idea, this is how you would load a heightmap at a given position and size:
var heightmap_data = Geodot.get_raster_layer("/path/to/data.tif")
var img = heightmap_data.get_image(
pos_x,
pos_y,
size_meters,
resolution,
1
)
var texture = img.get_image_texture()An Array of Vector features near a given position can be loaded like this:
var dataset = Geodot.get_dataset("/path/to/data.gpkg")
var layer = dataset.get_feature_layer("layername")
var features = layer.get_features_near_position(pos_x, pos_y, radius, max_features)If you want to add the Geodot addon to your own game, copy the addons/geodot directory to your project.
You will need some sort of geodata to use this plugin. The bundled demo scenes include small snippets of example data such as a raster heightmap and a vector street dataset.
For building this project we need to install Scons by following one of the User Guide Installing Scons which is both used for Godot GDExtension and this project and we need the GDAL library which has different installation instruction listed below.
- Install GDAL. (With apt:
sudo apt install libgdal-dev) - Initialize all git submodules:
git submodule update --init --recursive - Generate the GDExtension C++ bindings:
cd godot-cpp; scons platform=linux generate_bindings=yes
Everything is built via SConstruct. Running scons platform=linux in the root directory will compile everything: First the processing libraries, then the finished GDExtension plugin.
If you're working on a processing library, you can also only compile this library with the same scons platform=linux command in that library's directory (e.g. in src/raster-tile-extractor).
For building a self-contained plugin for use in other projects, it is recommended to move libgdal into the same directory as libgeodot and the other libraries (demo/addons/geodot/x11/).
Because of very inconsistent results with native Visual Studio compilation, we use Docker to create Windows builds from a Linux environment using MinGW. This means that Windows builds are also created on a Linux machine. We recommend the following process on Linux or on WSL (they will not work on native Windows):
- Install Docker, SCons, and MinGW
- Initialize all git submodules:
git submodule update --init --recursive - Generate the GDExtension C++ bindings:
cd godot-cpp; scons platform=windows generate_bindings=yes - Create the build container:
docker build -f DockerfileMinGW -t gdal-mingw .
Build Geodot on the container: docker run --name mingw-builder gdal-mingw:latest
Copy the resulting Geodot library: docker cp mingw-builder:/geodot/demo/addons/geodot/win64 ./demo/addons/geodot
Copy the DLLs for GDAL and all dependencies: docker cp mingw-builder:/usr/x86_64-w64-mingw32/sys-root/mingw/bin ./tmp and cp ./tmp/*.dll ./demo/addons/geodot/win64/
- The current implementation only has support for x86 and not for the new M1 processor.
- VectorExtractor is causing the game to crash. See #51
- You have to move some generated files. See #52
- Install using
brew install gdalor manually https://github.com/OSGeo/gdal. - Check installation with ie
gdalinfo --formats - Use
brew info gdal | grep '/usr/local' | cut -d ' ' -f 1orwhich gdalinfoto find the GDAL install location. - Make a note of this path like
/usr/local/Cellar/gdal/3.2.1and use that below forosgeo_path=... - Initialize all git submodules:
git submodule update --init --recursive - Generate the GDExtension C++ bindings:
cd godot-cpp
scons generate_bindings=yes target=release --jobs=$(sysctl -n hw.logicalcpu)
cd ..
- Compile the project itself using the GDAL location like
scons target=release osgeo_path=/usr/local/Cellar/gdal/3.2.1 - This generates the file
libgeodot.dyliband 2 more located indemo/addons/geodot/macos - Move the files
libRasterTileExtractor.dylibandlibVectorExtractor.dylibfromdemo/addons/geodot/macosintodemo/builddirectory. See #52 mkdir build ; mv demo/addons/geodot/macos/libRasterTileExtractor.dylib demo/addons/geodot/macos/libVectorExtractor.dylib demo/build
We recommend VSCodium for developing. For on-the-fly code completion, error reporting, etc., install the clangd extension in VSCodium and run scons compiledb=yes in order to generate the required compilation database.
A minimal Godot project which the plugin is compiled into by default. Used to test its functionality.
Git submodule with everything that's required for building a GDExtension plugin with C++.
geodot.h, geodata.h, etc. - the GDExtension C++ code for the actual plugin. It mainly acts as an interface from Godot-compatible types to custom libraries and classes - it is kept as simple as possible so that adapting it to changes in Godot is easy.
Processing Libraries handle calls to external libraries and convert the results to generic custom classes (independent and unaware of Godot). This way, Godot and external libraries are decoupled, with only one dependency per project.
The reason for this layer of abstraction is ease of compilation and extendibility: The libraries can remain the same, only the core Geodot must be kept consistent with Godot. Similarly, changes in external libraries only affect the corresponding processing library, not the Geodot layer.
Processing library called by Geodot. Wraps GDAL's Raster functionality, primarily the extraction of Raster data into an array.
Another processing library like the RasterTileExtractor. Also uses GDAL internally, but for vector data functionality, as well as general database and layer handling.
Help is greatly appreciated! You can test and report bugs, fix known issues or submit new functionality.
- Actual processing code and external library calls should be put into a separate project (a processing library) which compiles to a library and is independent from Godot.
- Geodot should only translate Godot calls and types to calls to this custom library. Its only dependencies should be Godot and custom libraries.
Summed up, dependencies should only go in this direction: Godot + Geodot -> Processing Library -> External Libraries
The provided Linux build ships with libgdal.so, a build of the GDAL library. All credits for this library go to OSGeo/gdal (license).
The RasterDemo ships with a small sample of Viennese test data (CC BY 4.0); the VectorDemo uses a sample of edges from the GIP dataset (CC BY 4.0).