Cesium Terrain Builder

To build Cesium Terrain Builder from source on a UNIX system, ensure you have the requirements met and follow these steps:

1. Requirements Check:

   • GDAL: Version >= 2.0.0 is required. Specifically, you need a version that includes the min, max, med, q1, and q3 resampling algorithms (e.g., GitHub mirror commit 0a90a34).
   • GDAL Development Headers: You must have the GDAL source development header files installed.
   • CMake: Must be available in your path.

2. Build Process:

   • Download and unpack the source code.
   • Create a build directory and run CMake and Make.

3. Post-Installation:

   • On UNIX systems, you may need to run ldconfig to update the shared library cache.

Custom Installation Paths and Debug Builds:

• To create a Debug build, use the -DCMAKE_BUILD_TYPE=Debug flag.
• To install to a specific location, use the CMAKE_INSTALL_PREFIX directive.
• If GDAL is in a custom location, you must manually provide the library and include paths using GDAL_LIBRARY_DIR, GDAL_LIBRARY, and GDAL_INCLUDE_DIR.

# Standard UNIX build
mkdir build && cd build && cmake .. && make install

# Build with Debug type and custom install prefix
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/tmp/terrain ..

# Build with GDAL in a custom location
cmake -DGDAL_LIBRARY_DIR=/home/user/install/lib \
      -DGDAL_LIBRARY=/home/user/install/lib/libgdal.so \
      -DGDAL_INCLUDE_DIR=/home/user/install/include \
      ..

To ensure efficient terrain tile generation, follow these recommendations:

1. Spatial Reference System: Use input rasters in the same SRS as the output (typically WGS 84). If they differ, the tool will reproject, which incurs a performance penalty.
2. Raster Format: For large rasters, use a tile-based format rather than scanline-based. Choose a block size similar to the output tile size (e.g., 65x65 for terrain).
3. Overviews: Add overviews to your source dataset using gdaladdo. ctb-tile uses overviews that closely match the target zoom level resolution.
4. Virtual Rasters (VRT): Use gdalbuildvrt to composite multiple DEM files into a single VRT for input.
5. Memory Management:
   • Set the GDAL_CACHEMAX environment variable to a high value.
   • Use the --warp-memory flag.
   • Tip: Try setting the combined value of GDAL_CACHEMAX and --warp-memory to approximately 2/3 of your available RAM.
6. Handling Large Datasets (Pyramidal Approach): To avoid performance issues or overflows at low zoom levels (e.g., level 0) when processing massive rasters, generate tiles in stages:
   • Generate only the highest zoom level (e.g., level 18) using --start-zoom and --end-zoom.
   • Convert that tileset into a GDAL VRT or DEM format.
   • Use that intermediate product to generate the next level down (e.g., level 17).
   • Repeat until level 0 is reached.

The ctb::Grid class is a generic model for cutting an area into zoom levels and tiles. It provides the mathematical logic to relate native Coordinate Reference System (CRS) coordinates to specific tiles and pixel locations.

Key functionalities include:

• Converting CRS coordinates to tile coordinates at a specific zoom level (crsToTile).
• Calculating the CRS bounds of a specific tile (tileBounds).
• Converting between pixel coordinates and CRS coordinates (pixelsToCrs, crsToPixels).
• Determining the resolution or zoom level for a given resolution (resolution, zoomForResolution).

While Grid is a general implementation, specific Tile Mapping Service profiles like GlobalMercator and GlobalGeodetic are implemented as subclasses.

// Example conceptual usage of the Grid interface
// Note: Actual instantiation requires specific parameters or a subclass
ctb::Grid grid(tileSize, extent, srs, rootTiles, zoomFactor);

// Get tile coordinate for a CRS point at a specific zoom level
ctb::TileCoordinate tile = grid.crsToTile(someCrsPoint, currentZoom);

// Get the spatial bounds of that tile in the native CRS
ctb::CRSBounds bounds = grid.tileBounds(tile);

Options for the ctb-tile [options] GDAL_DATASOURCE command.

  -V, --version                 output program version
  -h, --help                    output help information
  -o, --output-dir <dir>        specify the output directory for the tiles (defaults to working directory)
  -f, --output-format <format>  specify the output format for the tiles. This is either `Terrain` (the default) or any format listed by `gdalinfo --formats`
  -p, --profile <profile>       specify the TMS profile for the tiles. This is either `geodetic` (the default) or `mercator`
  -c, --thread-count <count>    specify the number of threads to use for tile generation. On multicore machines this defaults to the number of CPUs
  -t, --tile-size <size>        specify the size of the tiles in pixels. This defaults to 65 for terrain tiles and 256 for other GDAL formats
  -s, --start-zoom <zoom>       specify the zoom level to start at. This should be greater than the end zoom level
  -e, --end-zoom <zoom>         specify the zoom level to end at. This should be less than the start zoom level and >= 0
  -r, --resampling-method <algorithm> specify the raster resampling algorithm.  One of: nearest; bilinear; cubic; cubicspline; lanczos; average; mode; max; min; med; q1; q3. Defaults to average.
  -n, --creation-option <option> specify a GDAL creation option for the output dataset in the form NAME=VALUE. Can be specified multiple times. Not valid for Terrain tiles.
  -z, --error-threshold <threshold> specify the error threshold in pixel units for transformation approximation. Larger values should mean faster transforms. Defaults to 0.125
  -m, --warp-memory <bytes>     The memory limit in bytes used for warp operations. Higher settings should be faster. Defaults to a conservative GDAL internal setting.
  -R, --resume                  Do not overwrite existing files
  -q, --quiet                   only output errors
  -v, --verbose                 be more noisy