/DSM-Occlusion

Fast, ray-traced, ambient occlusion for raster models

Primary LanguageCudaGNU Affero General Public License v3.0AGPL-3.0

DSM Occlusion

Fast, ray-traced, occlusion for raster models

DSM Occlusion example


Key features

  • GPU accelerated
    Using CUDA reduces the computation time by order of magnitudes compared to other programs.
  • Automated tiling
    Large files are automatically split into tiles, with configurable size and margins (buffers to avoid border effects).
  • Handles large models
    Given enough disk space, can process files of several terabytes.
  • Ray-traced rendering
    Occlusion is computed using ray-tracing, simulating the real behavior of light rays.

Installation

This software requires a computer with an Nvidia graphic card and its driver installed.
Supported operating systems are Windows and Linux.

Windows

  1. Download the release from this repository and run the executable contained in it from a command line.

Linux

  1. Install the package of GDAL version 30 for your distribution. The package is generally named gdal or libgdal.

  2. Download the latest release from this repository and run the executable contained in it from a command line.


Usage

  • -i inputFile
    mandatory parameter
    Path to the input file. Must be a file supported by GDAL like .tif

  • -o outputFile
    optional parameter, default value : output.tif
    Path to the output file, where the result will be written

  • -r raysPerPixel
    optional parameter, default value : 256
    Number of rays to launch for each pixel. Increasing the parameter decreases the noise and increases the render quality and rendering time.

    • lower than 256 = low quality (noise is very noticeable)
    • lower than 1024 = medium quality (noise is noticeable, but limited)
    • lower than 2048 = high quality (noise is almost not noticeable)

  • -t tile size (in pixels)
    optional parameter, default value : 2000
    The input file is processed in square tiles. This parameter controls the tile side length.
    Smaller tiles are computed faster, but lead to a larger buffer surface (see next parameter) and may create border error if the buffers are not large enough.
    Larger tiles are more computation heavy for the GPU.
    The optimal value for this parameter strongly depends on your graphic card, don't hesitate to try multiple sizes.

  • -b tile buffer (in pixels)
    optional parameter, default value : 1/3 of the tile size
    The input file is processed in square tiles. To avoid border error, tiles are overlapping. This parameter controls the tile overlapping amount (in pixels) in each direction.

  • -e exaggeration
    optional parameter, default value : 1.0 This parameter scales all input values by the given factor. A value higher than 1.0 makes the shadows darker, revealing more details.

  • -B maximum bounces optional parameter, default value : 0 The maximum number of times a ray can bounce on the geometry before the ray is considered not reaching the sky. The higher the value, the more accurate and luminous the result will be. Increase this value will drastically increase the processing time!. A value of 0 (the default) leads to the same result as computing the sky view factor.

  • --bias optional parameter, default value : 1.0 Bias applied to rays distribution. A value of 1 means no bias, and the rays are uniformly sampled in all directions. Values greater than 1 bias rays toward the horizon, revealing small terrain details but darkening already occluded areas. Values smaller than 1 bias rays toward the zenith, brightening dark areas and discarding terrain details.

  • --info
    optional parameter
    Prints information about the GDAL driver and the graphic card. This is purely informative.

Example : DSM_Occlusion -i /path/to/input.tif -o /path/to/output.tif -r 1024


Build instructions
(setting up a development environment)

Windows

  1. Make sure you have installed the following :

    • Git (used to clone this repository)
    • Microsoft Visual Studio Community
      • Install "Desktop development with C++" including :
        • "MSVC C++ x64/x86 build tools"
        • "C++ CMake tools for Windows"
        • Windows SDK for your current Windows installation (ex. "Windows 11 SDK" for Windows 11)
    • CUDA Toolkit
    • GDAL / GDAL-devel
      • The easiest way to get GDAL is through OSGeo4W
      • You can automatically install GDAL by running the following command in a terminal : osgeo4w-setup.exe -q -r -s https://download.osgeo.org/osgeo4w/v2/ -P gdal -P gdal-devel

  2. Clone this repository

  3. Open a "x64 Native Tools Command Prompt for VS 2022" (or your current VS version). Can be found by searching for it in the Windows.

  4. Navigate to the repository root and generate the project using the command cmake -B ./build Then build the project using cmake --build ./build --config Release. The executable is located in ./build/Release.

  5. To start the executable, add the folder containing the GDAL .dll files to your PATH environment variable. If installed using OSGeo4W, the default path is C:\OSGeo4W\bin.

Note : You can also generate the executable by running msbuild ./build/DSM_Occlusion.sln /p:Configuration=Release /p:Platform=x64 /p:OutDir=<output_directory>

Linux

  1. Install the following packages for your distribution :

    • Git, CMake, CUDA Toolkit and GDAL

    • For the following distributions :

      • Arch : sudo pacman -Syu git cuda cmake gdal
      • Ubuntu :
        • Install CMake and GDAL : sudo apt-get install git cmake libgdal-dev
        • Download CUDA Toolkit from the official site (https://developer.nvidia.com/cuda-downloads). Select your preferred installer type and follow the instructions for the Base Installer.
      • Other distributions :
        • Git and CMake : these are widely available from any distribution
        • GDAL : Depends on the distribution. The development package is often called gdal-devel or libgdal-dev.
        • CUDA Toolkit : Download it from the official site (https://developer.nvidia.com/cuda-downloads). Select your preferred installer type and follow the instructions for the Base Installer.

  2. Clone this repository and navigate to its root.

  3. Generate the project using the command cmake -B ./build.
    Then build the project using cmake --build ./build --config Release

macOS

  • macOS is currently not supported. Contributions are welcome !

Troubleshooting

  • Unable to find GDAL library during build
    Reason : The GDAL library files (.lib on Windows, or .so on Linux) failed to be located.
    Solution : Make sure GDAL is installed properly. If GDAL library is not installed in the expected directory (/usr/lib/ on Linux, or C:/OSGeo4W/lib/ on Windows) you can specify GDAL library location by defining GDAL_LIB_DIR during CMake generation. Example : cmake -B ./build -DGDAL_LIB_DIR=<your_gdal_path>

  • gdal_priv.h not found during build
    Reason : The GDAL header files (.h) failed to be located.
    Solution : Make sure GDAL is installed properly. If GDAL headers are not installed in the expected directory (/usr/include/ on Linux, or C:/OSGeo4W/include/ on Windows) you can specify GDAL headers location by defining GDAL_INCLUDE_DIR during CMake generation. Example : cmake -B ./build -DGDAL_INCLUDE_DIR=<your_gdal_path>

  • Unsupported gpu architecture during build
    Reason : By default, the project is compiled for the hardware on the current machine. This error happens if CUDA was not able to find the current machine architecture (for example, when the current machine doesn't have a GPU).
    Solution : You can specify the GPU architecture to use by defining CMAKE_CUDA_ARCHITECTURES during generation. Example : cmake -B ./build -DCMAKE_CUDA_ARCHITECTURES=75. See CMAKE_CUDA_ARCHITECTURES.

  • Missing CUDA driver or CUDA driver version is insufficient when running the executable
    Reason : Your CUDA driver is either missing or too old.
    Solution : Install the latest CUDA driver for your system and graphic card.